La mejor manera de aprender es haciendo, learn by doing, por eso, no hay nada como montar un servidor MCP (Model Context Protocol) y verlo funcionar dentro de Claude para entender realmente cómo funciona. La parte buena es que para poder montar un servidor MCP en Python no es necesario entender a la perfección todo el protocolo antes de comenzar, son sólo diez líneas tienes algo real, compatible con cualquier cliente y que le puedes pedir que ejecute.
Si quieres tener más claro qué es MCP y por qué está ganando tanta tracción, puedes revisar más detalle en este post. Aquí vamos directos al código: vas a escribir tu primer servidor, probarlo de forma aislada con MCP Inspector y conectarlo a Claude Desktop para usarlo en una conversación real.
El servidor mínimo: diez líneas que ya hablan el protocolo
Esto es todo lo que necesitas para tener un servidor MCP funcionando:
from mcp.server.fastmcp import FastMCP
mcp = FastMCP("mi-primer-servidor")
@mcp.tool()
def saludar(nombre: str) -> str:
"""Saluda a una persona por su nombre."""
return f"Hola, {nombre}."
if __name__ == "__main__":
mcp.run()
Guarda esto en un fichero server.py, instala el SDK (pip install mcp) dentro de un entorno virtual, y ya tienes un servidor MCP real. Esto no es un esqueleto, es un servidor que implementa el protocolo completo y expone una Tool que cualquier cliente puede listar y ejecutar.
Pasan tres cosas en este código. Primero, creas una instancia de FastMCP con un nombre, ese nombre es el que verá el cliente cuando liste los servidores disponibles. Segundo, defines una función Python normal y corriente, y la decoras con @mcp.tool(). Tercero, arrancas el servidor con mcp.run(), que por defecto usa transporte stdio, esto quiere decir que el servidor se comunica por entrada/salida estándar, no por red.
FastMCP es la clase de alto nivel del SDK oficial. Existe una API de más bajo nivel para casos avanzados, pero para la inmensa mayoría de los casos FastMCP te ahorra toda la fontanería del protocolo: handshake, serialización de mensajes, gestión de la sesión. Empieza por aquí.
Qué hace exactamente @mcp.tool()
El decorador @mcp.tool() hace más de lo que parece a simple vista. No solo registra la función como una Tool disponible: lee su firma de tipos y su docstring para construir automáticamente el esquema que el cliente envía al modelo.
Ese esquema no lo ve el usuario. Lo ve el modelo, en el momento en que decide qué herramientas tiene disponibles para responder. Por eso la descripción que escribes en el docstring importa tanto como el código de la función.
@mcp.tool()
def buscar_producto(nombre: str, categoria: str = "todos") -> dict:
"""
Busca productos en el catálogo por nombre y categoría opcional.
Usa esta herramienta cuando el usuario quiera encontrar un producto
o preguntar por su disponibilidad.
"""
...
Hay un patrón que funciona bien: una primera línea corta que dice qué hace la herramienta, y luego una o dos líneas que indican cuándo debe usarse. Si la descripción es vaga, el modelo puede no saber cuándo invocarla, o peor, invocarla cuando no toca. Una descripción precisa hace que el modelo la use exactamente cuando corresponde.
Validación automática a partir de los tipos
El SDK convierte las anotaciones de tipo de Python en el esquema JSON de la Tool. Si defines un parámetro como int, el cliente valida que lo que llega es un entero antes de ejecutar tu función. Si no lo es, el modelo recibe un error de validación sin que tu código llegue a correr.
Para empezar te bastan los tipos básicos: str, int, float, bool, listas y diccionarios se traducen de forma directa al esquema. Si necesitas algo más estructurado, un objeto con varios campos opcionales por ejemplo, el SDK acepta modelos Pydantic como tipo de parámetro y genera el esquema completo a partir de ellos. Pero para tu primer servidor, los tipos básicos son más que suficientes.
Probarlo sin montar nada más: MCP Inspector
Antes de tocar Claude Desktop, conviene comprobar que el servidor funciona de forma aislada. Para eso existe MCP Inspector, una herramienta de línea de comandos que levanta una interfaz web para hablar directamente con tu servidor:
npx @modelcontextprotocol/inspector python server.py
Abre en el navegador la URL que aparece en consola, pulsa Connect y deberías ver el nombre de tu servidor (mi-primer-servidor). En la pestaña Tools, pulsa List Tools: el Inspector le pregunta al servidor qué herramientas tiene registradas, y debería aparecer saludar con el esquema generado a partir del docstring y la anotación de tipo.
Escribe un valor para nombre, ejecuta, y si la respuesta es "Hola, [tu nombre].", el servidor funciona de principio a fin. Vale la pena probar también el caso contrario: ejecuta la Tool sin pasar el parámetro y verás el error de validación automático del SDK. Saber qué pinta tiene ese error te ahorra tiempo cuando algo falle más adelante, en un servidor con más piezas.
Conectarlo a Claude Desktop
Con el Inspector confirmando que todo funciona, el último paso es conectar el servidor a Claude Desktop. La configuración vive en un fichero JSON cuya ubicación depende del sistema operativo:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
Si el fichero no existe, créalo con esta estructura, sustituyendo la ruta por la absoluta a tu server.py:
{
"mcpServers": {
"mi-primer-servidor": {
"command": "python",
"args": ["/ruta/absoluta/a/tu/server.py"]
}
}
}
Usa siempre rutas absolutas, las relativas no funcionan. Si trabajas con un entorno virtual, apunta command directamente al Python de ese entorno en lugar del global del sistema.
Guarda el fichero y reinicia Claude Desktop por completo: cerrar la ventana no es suficiente, tienes que cerrar el proceso desde el icono de la bandeja del sistema y volver a abrirlo. Al arrancar, verás un icono de herramienta en la barra del chat indicando cuántos servidores MCP están conectados. Si haces clic, debería aparecer saludar en la lista.
A partir de ahí, escríbele a Claude "saluda a María". Claude lee la lista de Tools disponibles, decide que saludar es la adecuada, la ejecuta con nombre="María" y te devuelve la respuesta. Tu primer servidor MCP, funcionando en una conversación real.
De aquí a un servidor útil
Esta primera Tool tiene una utilidad casi nula, pero la estructura es exactamente la misma que la de un servidor que lee ficheros, consulta una base de datos o llama a una API externa. Lo que cambia es lo que hace la función decorada y cuántas Tools defines. La curva de aprendizaje real de MCP no está en el protocolo, está en diseñar bien esas funciones: qué validar, qué devolver, qué errores manejar y dónde está el límite entre lo que puede tocar el servidor y lo que no.
Si quieres ver esa parte aplicada a casos reales, un servidor que lee y escribe ficheros, otro que envuelve una API REST, uno con SQLite, un scraper y un ejecutor de código, monté los cinco paso a paso, con el código completo y las decisiones de diseño explicadas, en MCP de 0 a Producción.