Entiende la anatomía completa de un MCP Server: desde la importación hasta el registro de tools y el ciclo de vida de una solicitud.
Un MCP Server en Python con FastMCP es sorprendentemente sencillo. Con apenas ~10 líneas de código, tienes un servidor funcional completo, listo para recibir solicitudes de cualquier client MCP compatible. La estructura sigue un patrón claro: imports, creación de la instancia del server, funciones decoradas con @mcp.tool() y el punto de entrada. Cada parte cumple una función específica y esencial para que el servidor funcione.
La anatomía de un MCP Server con FastMCP tiene cuatro componentes fundamentales: Import — incorpora el framework FastMCP a tu código; Instancia — crea el objeto server con un nombre identificador; Tools — funciones de Python decoradas con @mcp.tool() que el modelo puede llamar; y Punto de entrada — el bloque if __name__ == "__main__" que inicia el servidor. Con solo estas cuatro piezas, tienes un MCP Server funcional en ~10 líneas de código.
La estructura mínima de un MCP Server es: (1) from fastmcp import FastMCP — (2) mcp = FastMCP("meu-server") — (3) una función decorada con @mcp.tool() — (4) mcp.run() en el bloque main. Memoriza esta secuencia: importar → instanciar → decorar → ejecutar. Todos los MCP Servers siguen este patrón, desde los más simples hasta los más complejos.
Todo empieza con dos líneas de código: el import de FastMCP y la creación de la instancia del server. Estas dos líneas establecen los cimientos sobre los que se construye todo lo demás. El nombre que le das al server es importante: así es como el client MCP lo identifica y se lo muestra al usuario. Elige nombres descriptivos y coherentes.
La inicialización de un MCP Server ocurre en dos pasos: from fastmcp import FastMCP — importa la clase principal del framework — y mcp = FastMCP("nome-do-server") — crea la instancia del server con un nombre identificador. El nombre que se pasa como argumento es el que aparece en el client (como Claude Desktop) para que el usuario sepa qué server está disponible. Este nombre debe ser único y describir el propósito del server.
FastMCP es el framework oficial recomendado por Anthropic para crear MCP Servers en Python. Abstrae toda la complejidad del protocolo MCP (JSON-RPC, transporte stdio/SSE, negociación de capabilities) en una API sencilla basada en decorators. Con FastMCP, lo que antes requería cientos de líneas de código de bajo nivel ahora requiere menos de 10 líneas. Es la forma más rápida y recomendada de crear un MCP Server.
El corazón de un MCP Server son las tools — funciones Python que el modelo de IA puede llamar. FastMCP usa el decorator @mcp.tool() para transformar cualquier función común de Python en una tool MCP accesible para el cliente. Los parámetros de la función se convierten en los parámetros de la tool, las anotaciones de tipo definen el schema y el docstring se convierte en la descripción que el modelo lee para decidir cuándo usar la tool.
El decorator @mcp.tool() es el puente entre Python y el protocolo MCP. Cuando decoras una función con él, suceden tres cosas automáticamente: (1) El nombre de la función se convierte en el nombre de la tool; (2) Los type hints de los parámetros se convierten en JSON Schema para la validación; (3) La docstring de la función se convierte en la descripción que el modelo usa para entender el propósito de la tool. Sin necesidad de escribir una sola línea de configuración.
Piensa en el decorator @mcp.tool() como un insignia de publicación: cuando pones el sello en una función, estás diciendo "esta función está disponible para que la use la IA". Sin el sello, la función es solo código Python interno. Con el sello, se convierte en una capability del server, visible para cualquier client MCP conectado. Cada función decorada se registra automáticamente en la lista de tools del server.
Escribes una función Python normal con type hints y docstring, como lo harías en cualquier proyecto Python.
Agrega el decorador @mcp.tool() encima de la función: FastMCP detecta y registra la tool automáticamente.
FastMCP extrae el nombre, los parámetros (mediante type hints) y la descripción (mediante docstring), y genera automáticamente el JSON Schema.
Cuando el client se conecta, el server envía la lista de tools disponibles, y el modelo sabe exactamente cómo llamarlas.
Un MCP Server no es un programa que se ejecuta y termina: es un proceso que permanece activo, a la espera de conexiones y procesando solicitudes continuamente. Entender el ciclo de vida completo del server es fundamental para depurar problemas, optimizar el rendimiento y crear servers robustos que funcionen de forma confiable en producción.
El ciclo de vida de un MCP Server sigue una secuencia bien definida: el server inicia cuándo lo ejecuta el client; registra sus capabilities (tools, resources, prompts); espera conexiones vía stdio o SSE; recibe solicitudes del client (llamadas a tools); ejecuta la lógica de la tool llamada; devuelve el resultado al cliente; y vuelve a esperar la siguiente solicitud. Este ciclo se repite hasta que el client cierre la conexión.
El client (ej.: Claude Desktop) ejecuta el comando configurado. Se inicia el proceso de Python y FastMCP carga todas las tools decoradas.
El server envía al client la lista de todas las tools, resources y prompts disponibles, junto con sus schemas y descripciones.
El server permanece en un loop esperando mensajes del client mediante el transporte configurado (stdio para procesos locales, SSE para remotos).
Cuando el modelo decide usar una tool, el client envía un mensaje JSON-RPC con el nombre de la tool y los argumentos.
FastMCP localiza la función correspondiente, valida los parámetros según el schema y ejecuta la función de Python.
El resultado se serializa y se envía de vuelta al client. El server vuelve al estado de espera, listo para la siguiente solicitud.
Un MCP Server puede ser tan sencillo como un único archivo Python o estar tan organizado como un proyecto completo con pruebas, documentación y módulos separados. La elección depende de la complejidad de lo que estés creando. Para aprender y hacer prototipos, basta con un proyecto mínimo. En producción, una estructura organizada marca una gran diferencia en la facilidad de mantenimiento.
Proyecto mínimo — bastan dos archivos: pyproject.toml (metadatos y dependencias) y server.py (código del server). Eso es todo lo que necesitas para tener un MCP Server funcional. Proyecto completo — para servers más robustos, organiza con: directorio src/ para código fuente, tests/ para pruebas, README.md para documentación y, potencialmente, varios módulos para separar responsabilidades.
El archivo pyproject.toml es el centro de configuración de tu proyecto de Python. Allí se definen las dependencias (como FastMCP), los metadatos del proyecto y, opcionalmente, los entry points que facilitan la ejecución. El uv es el gestor de proyectos recomendado: se encarga del entorno virtual, las dependencias y la ejecución de forma rápida y confiable.
O pyproject.toml define: el nombre del proyecto, la versión de Python requerida, las dependencias (incluido fastmcp), y, de forma opcional, entry points con [project.scripts]. O uv lo gestiona todo: crea el entorno virtual automáticamente, instala dependencias rápidamente y permite ejecutar el server con uv run server.py. Juntos, pyproject.toml y uv eliminan la complejidad de configurar el entorno de Python.
Usa uv init nome-do-projeto para crear pyproject.toml automáticamente, y uv add fastmcp para agregar la dependencia. uv creará el entorno virtual, resolverá las dependencias y actualizará pyproject.toml, todo con un solo comando. Nunca más tendrás que hacer pip install manualmente o administrar virtualenvs a mano.
Asegúrate de que el uv esté instalado en tu máquina antes de empezar. Claude Desktop ejecuta el server con el comando uv run, así que, si uv no está disponible en el PATH, el server simplemente no se iniciará y el error podría ser silencioso. Verifica con uv --version antes de continuar. Si no está instalado, usa curl -LsSf https://astral.sh/uv/install.sh | sh.
from fastmcp import FastMCP e mcp = FastMCP("nome") — el nombre identifica el server en el client.
@mcp.tool() transforma funciones Python en tools MCP y extrae automáticamente el nombre, los parámetros y la descripción.
uv init e uv add fastmcp para comenzar.
Siguiente Módulo: 3.2 — Hello World MCP