Crea tu primer servidor MCP en Python paso a paso

Llevas meses haciendo de cable entre tus datos y la inteligencia artificial. Exportas un Excel, copias una tabla, pegas información en el chat, pides un resumen, vuelves a copiar, vuelves a pegar. Y al día siguiente, otra vez. La IA es brillante, sí, pero solo conoce lo que tiene dentro de su contexto. No puede entrar por arte de magia en tu CRM, consultar tu base de datos, revisar el catálogo de tu empresa o leer ese fichero que cambia cada mañana. Es como tener un cerebro espectacular encerrado en una habitación sin ventanas. Un servidor MCP soluciona precisamente eso. Te permite conectar una inteligencia artificial con tus fuentes de datos y con acciones reales, de forma reutilizable y sin tener que volver a pegar información a mano.

Qué es MCP y por qué importa tanto

MCP significa Model Context Protocol. Es un estándar que permite que asistentes de inteligencia artificial y fuentes externas de información hablen el mismo idioma.

La comparación más sencilla es USB-C. Durante años, cada dispositivo tenía su cable propietario. Conectar algo implicaba encontrar el conector correcto, comprar adaptadores y cruzar los dedos. Con USB-C, existe un conector común para muchos dispositivos.

Con MCP ocurre lo mismo. En vez de construir una integración específica para cada combinación de asistente y fuente de datos, creas un servidor MCP que puede ser utilizado por clientes compatibles. Da igual que trabajes con Claude, GPT, modelos locales como Llama o Kimi, o una aplicación de desarrollo como Cursor.

La diferencia es enorme. Si tienes cinco asistentes y cinco fuentes de datos, no necesitas mantener veinticinco integraciones distintas. Necesitas cinco servidores y cinco clientes que sepan hablar MCP. Menos caos, menos mantenimiento y mucha más capacidad para reutilizar tu trabajo.

Las tres piezas de un servidor MCP

Un servidor MCP puede ofrecer tres tipos de elementos. El patrón es muy fácil de recordar:

• Tools o herramientas: acciones que la IA puede ejecutar.
• Resources o recursos: datos que la IA puede leer.
• Prompts: plantillas de instrucciones que se invocan manualmente.

Una regla rápida funciona bastante bien: si lleva verbo, normalmente es una herramienta. Si es un sustantivo, probablemente es un recurso.

Por ejemplo, buscar cursos, crear un ticket o enviar un correo son herramientas. En cambio, catálogo de cursos, ficha de producto, contenido de un documento o tabla de clientes son recursos.

Los prompts también existen, pero suelen ser menos relevantes para un primer proyecto. Si estás arrancando, una herramienta y un par de recursos ya te permiten entender la arquitectura completa.

Host, cliente y servidor: quién habla con quién

En una integración MCP hay tres actores:

• El host: la aplicación desde la que trabajas, como Claude Code, Claude Desktop o Cursor.
• El cliente MCP: vive dentro del host y se encarga de conectarse.
• El servidor MCP: tu código, que expone datos y acciones.

Hay un detalle que suele confundir al principio: un servidor MCP local no tiene por qué ser una web levantada permanentemente en un puerto. En el caso más habitual, el propio cliente inicia el servidor como un subproceso cuando lo necesita.

Para empezar, quédate con un transporte: stdio. El cliente y el servidor se comunican a través de la entrada y salida estándar del proceso. Es sencillo, local y perfecto para experimentar con tus propios archivos, bases de datos o automatizaciones.

También existe Streamable HTTP, pensado para servidores remotos que se alojan en la nube, se comparten con un equipo o se publican para otros usuarios. Pero no empieces por ahí. Stdio cubre una cantidad enorme de casos reales y es la ruta más corta para construir algo útil.

El ejemplo práctico: un catálogo conectado a la IA

Imagina un servidor MCP que expone un catálogo de cursos. En lugar de pegar la información del catálogo en una conversación, la IA puede consultar ese catálogo cuando detecta que la pregunta lo requiere.

Para ello puedes crear:

• Una herramienta para buscar cursos por temática, nivel u objetivo.
• Un recurso que devuelva el índice completo del catálogo.
• Un recurso dinámico que devuelva la ficha de un curso concreto a partir de su slug.

En un proyecto de demostración, los datos pueden vivir en un fichero JSON con campos como título, nivel, duración y temáticas. Pero el cambio a un caso de producción es directo: sustituyes ese JSON por tu base de datos, tu CRM, tu ERP, una API interna o incluso tus propios ficheros Excel.

Ahí está la gracia. No estás creando una demo de “hola mundo”. Estás creando una capa para que la inteligencia artificial consulte información viva, que cambia y que antes dependía de que tú hicieras de mensajero.

FastMCP y SDK oficial: el lío que rompe tutoriales

Antes de tocar código hay que aclarar una fuente de confusión bastante importante. Existen dos librerías que se mezclan constantemente en tutoriales y ejemplos:

• FastMCP: un proyecto independiente, activo y en evolución.
• El SDK oficial mcp: la implementación oficial del protocolo.

Durante un tiempo, el SDK oficial incluía una copia interna de FastMCP 1.0. Con la llegada de versiones más nuevas del SDK, esa copia dejó de estar disponible. Resultado: muchos ejemplos antiguos intentan importar una ruta que ya no existe y fallan en la primera línea.

Si te ocurre, no es necesariamente que hayas instalado mal la dependencia. Muchas veces el tutorial simplemente se ha quedado viejo. En un ecosistema que evoluciona tan rápido como MCP, las rutas de importación, versiones y APIs pueden cambiar de forma radical en pocos meses.

La buena noticia es que los conceptos importantes permanecen. Tools, resources, firmas de funciones, anotaciones de tipos y documentación siguen siendo la base. Para el ejemplo, el SDK oficial es una opción limpia y directa, sin añadir dependencias que no necesitas.

Tu docstring no es documentación: es el prompt de la herramienta

Esta es probablemente la idea más importante de todo el servidor MCP.

Cuando decoras una función como herramienta, el SDK puede generar automáticamente el esquema necesario leyendo la firma de Python. El nombre de los parámetros, sus anotaciones de tipo y sus valores por defecto sirven para construir la definición que utilizará el cliente.

Eso significa que no necesitas escribir a mano un esquema JSON gigantesco para cada acción. Defines una función bien tipada y el framework hace buena parte del trabajo.

Pero hay una parte que exige especial atención: el docstring.

El docstring no es un comentario bonito para ti. Es la instrucción que el modelo utilizará para decidir cuándo debe llamar a tu herramienta. Si escribes algo vago como “Busca cursos”, no ayudas demasiado. La IA no sabe con claridad cuándo activarla.

En cambio, una descripción útil explica el contexto de uso. Por ejemplo:

• Úsala cuando se pregunte por cursos de una temática concreta.
• Úsala para recomendar formación según un objetivo.
• Úsala cuando se necesite comparar niveles, duración o contenidos.

Si una herramienta aparece correctamente registrada pero la IA nunca la utiliza, el problema no suele estar en la lógica de Python. Muchas veces el problema es que has escrito un prompt flojo dentro del docstring.

Resources estáticos y dinámicos

Los recursos son todavía más sencillos de entender. Un recurso puede tener una URI fija, como una dirección para consultar el catálogo completo. Pero también puede usar parámetros dinámicos.

Por ejemplo, un recurso con una estructura como curso://{slug} permite pedir la ficha de cualquier curso usando su identificador. El SDK se encarga de convertir ese valor dinámico en un parámetro de tu función y de resolver el enrutado.

Esto es muy potente porque permite que la IA consulte primero una herramienta de búsqueda y, después, lea el recurso exacto que necesita para responder. No necesita recibir todos los detalles de todos los productos desde el principio.

Prueba el servidor antes de conectarlo a Claude Code

Antes de enchufar nada a un asistente, utiliza el inspector del SDK. Instalar el extra de línea de comandos te permite arrancar una interfaz local para comprobar que tu servidor está bien definido.

El inspector te deja revisar:

• Las herramientas expuestas.
• Los recursos disponibles.
• Los prompts registrados.
• Las llamadas realizadas y sus tiempos.
• Los mensajes de consola y posibles errores.

La regla de oro es sencilla: si una herramienta, recurso o prompt no aparece en el inspector, no sigas adelante. El problema todavía está en tu servidor. No es culpa de Claude Code ni de la IA que vayas a conectar después.

Cómo registrar el MCP en Claude Code

Una vez que el servidor funciona en local, puedes registrarlo en Claude Code mediante un comando que indique el nombre del servidor, el directorio de ejecución y cómo arrancar Python.

Por defecto puedes usar un ámbito local, útil cuando quieres que el servidor solo exista para ti y dentro de un directorio concreto. Si trabajas con un equipo, puedes usar un ámbito de proyecto y guardar la configuración en un fichero que viaje con Git.

Eso sí, tiene sentido que el cliente pida aprobación. Nadie quiere hacer un git pull y que, sin avisar, se inicie un proceso nuevo en su máquina. Es una medida de seguridad, no un fallo.

La auténtica prueba llega cuando haces una pregunta normal, sin ordenar explícitamente que use la herramienta. Si preguntas qué cursos hay sobre agentes de IA y cuál es el más avanzado, la IA debería decidir consultar la herramienta, identificar los resultados y leer la ficha adecuada.

Eso es MCP funcionando de verdad. Los datos no estaban en el entrenamiento del modelo y nadie los pegó manualmente en el chat. El asistente los obtuvo desde la fuente que tú conectaste.

Los cuatro errores que te harán perder una tarde

1. El servidor no aparece. Casi siempre es un problema de ruta. El cliente guarda el comando tal como se lo indicaste, así que usa rutas absolutas o especifica correctamente el directorio de trabajo.
2. El servidor aparece, pero la IA no lo usa. Revisa el docstring. Explica cuándo debe utilizarse la herramienta, no solo qué hace.
3. Haces un print y todo explota. En stdio, la salida estándar forma parte del protocolo. Un print mete ruido en la conversación JSON-RPC. Para depurar, escribe siempre en stderr.
4. Devuelves respuestas gigantescas. Todo lo que devuelva una herramienta entra en el contexto del modelo y consume tokens. Devuelve solo lo necesario, con datos claros y legibles.

Cuándo no deberías montar un servidor MCP

No hace falta poner MCP hasta en la sopa.

Si lo único que quieres es proporcionar instrucciones estables, una guía de estilo, reglas internas o la forma en la que escribe tu equipo, utiliza una skill o un fichero de contexto como CLAUDE.md. No tiene sentido construir un servidor entero para servir un texto plano que nunca cambia.

Si necesitas ejecutar una acción concreta una única vez y sabes que siempre debe ocurrir, utiliza un script. Lo preparas, lo ejecutas y listo.

Un MCP tiene sentido cuando se cumple al menos una de estas condiciones:

• La fuente de datos está viva y cambia continuamente.
• La IA debe decidir cuándo consultar esa información.
• La IA debe decidir si ejecutar una acción concreta.
• Quieres reutilizar la integración en distintos asistentes compatibles.

Si la decisión de ejecutar código ya está tomada de antemano, probablemente necesitas automatización o un script. Si la IA tiene que decidir qué hacer según el contexto, entonces una herramienta MCP empieza a tener mucho sentido.

El siguiente paso: conecta tus datos reales

Ya tienes el patrón completo: herramientas, recursos, transporte stdio, pruebas en el inspector y registro en el cliente. Cambiar el JSON de ejemplo por una fuente real es la parte más fácil.

Empieza con algo pequeño pero útil: tus notas, un catálogo, una base de datos interna, una API de proyectos o una carpeta de documentos. En una tarde puedes dejar de copiar y pegar contexto todos los días y empezar a conectar la IA con información que realmente importa.

Y si quieres dominar la parte grande del puzle, porque MCP es solo la capa de herramientas de un agente, tienes el curso completo de Ingeniería de Agentes de IA, con el bucle de agentes, LangGraph, CrewAI, AutoGen y servidores MCP a fondo.

También puedes explorar la formación en Inteligencia Artificial de Frogames para seguir construyendo proyectos útiles, con código de verdad y sin humo.