Crea tu primer Plugin MCP con Python y FastMCP

¿Qué es un MCP y por qué deberías construir uno?

Los Model Context Protocol (MCP) son una especificación abierta que permite a los asistentes de IA, como Claude, acceder a herramientas y datos externos de forma segura y estandarizada. En lugar de limitarte a conversaciones estáticas, un plugin MCP convierte a tu asistente en un agente capaz de ejecutar código, consultar bases de datos, manipular archivos o interactuar con APIs. Con Python y la librería FastMCP, puedes crear tu propio plugin en minutos, sin necesidad de infraestructura compleja. Este artículo te guiará paso a paso para que construyas tu primer plugin funcional, desde la configuración inicial hasta la integración con un cliente MCP.

Preparación del entorno: instala FastMCP y configura tu proyecto

Antes de escribir código, asegúrate de tener Python 3.10 o superior instalado. FastMCP es una librería ligera que simplifica la creación de servidores MCP. Abre tu terminal y ejecuta:

BASHpip install fastmcp uvicorn FastMCP se encarga de manejar el protocolo MCP, mientras que Uvicorn sirve como servidor ASGI para ejecutar tu aplicación. Crea un archivo llamado plugin_mcp.py y escribe la estructura base:

PYTHONfrom fastmcp import FastMCP, Tool app = FastMCP() @app.tool() def saludar(nombre: str) -> str: """Saluda a una persona por su nombre.""" return f"Hola, {nombre}! Bienvenido a tu primer plugin MCP." @app.tool() def sumar(a: int, b: int) -> int: """Suma dos números enteros.""" return a + b Este código define dos herramientas: saludar y sumar. Cada función decorada con @app.tool() se convierte automáticamente en un endpoint MCP. FastMCP infiere los tipos de datos y genera el esquema JSON-RPC necesario para que el asistente de IA entienda cómo llamar a estas herramientas. Para probar localmente, ejecuta:

BASHuvicorn plugin_mcp:app --host 0.0.0.0 --port 8000 Si todo funciona, verás un mensaje indicando que el servidor está corriendo en http://0.0.0.0:8000. Puedes visitar esa URL en tu navegador para ver la interfaz de documentación automática de FastMCP.

Agrega herramientas con estado y acceso a datos externos

Un plugin MCP realmente útil necesita interactuar con el mundo exterior. Vamos a añadir una herramienta que lea un archivo JSON local y otra que realice una petición HTTP a una API pública. Modifica tu archivo plugin_mcp.py:

PYTHONimport json import httpx from fastmcp import FastMCP app = FastMCP() @app.tool() def leer_configuracion() -> dict: """Lee el archivo config.json y devuelve su contenido.""" with open("config.json", "r") as f: return json.load(f) @app.tool() async def obtener_clima(ciudad: str) -> dict: """Obtiene el clima actual de una ciudad usando la API de wttr.in.""" async with httpx.AsyncClient() as client: response = await client.get(f"https://wttr.in/{ciudad}?format=j1") return response.json() Observa que la segunda herramienta es asíncrona (async def). FastMCP soporta tanto funciones síncronas como asíncronas. Para que funcione, necesitas instalar httpx: pip install httpx. Además, crea un archivo config.json en la misma carpeta con contenido de prueba, por ejemplo:

JSON{ "nombre_app": "Mi Plugin MCP", "version": "1.0.0", "entorno": "desarrollo" } Reinicia el servidor Uvicorn y ahora tu plugin puede leer archivos locales y consultar APIs externas. El asistente de IA podrá invocar leer_configuracion para obtener parámetros de configuración o obtener_clima para responder preguntas sobre el tiempo.

Integra tu plugin con un cliente MCP (Claude Desktop)

Para que tu plugin sea usable desde un asistente como Claude, necesitas configurar un cliente MCP. Si usas Claude Desktop, ve a la configuración de MCP y agrega un nuevo servidor con la URL de tu servidor FastMCP (por ejemplo, http://localhost:8000). Si prefieres probar desde la línea de comandos, puedes usar mcp-cli:

BASHpip install mcp-cli mcp-cli connect http://localhost:8000 Una vez conectado, escribe mensajes como "saluda a Juan" o "suma 5 y 3". El cliente traducirá tu lenguaje natural a llamadas a las herramientas MCP. Para herramientas más complejas, como obtener_clima, puedes preguntar "¿cómo está el clima en Madrid?" y el asistente usará tu plugin para responder. Si tu plugin requiere autenticación o manejo de errores, FastMCP permite agregar middlewares y validaciones personalizadas.

Tip: Si tu plugin necesita mantener estado entre llamadas (por ejemplo, un contador de solicitudes), usa una variable global en el módulo Python. FastMCP no reinicia el servidor entre invocaciones, por lo que las variables persisten mientras el servidor esté activo. Eso sí, ten cuidado con la concurrencia si usas async.

Despliegue y consideraciones de seguridad

Para llevar tu plugin a producción, despliega el servidor FastMCP en un servicio como Railway, Render o un VPS. Asegúrate de usar variables de entorno para datos sensibles (API keys, rutas de archivos). FastMCP soporta autenticación básica mediante tokens: puedes agregar un decorador @app.require_auth("mi-token-secreto") en herramientas específicas. También es recomendable limitar las herramientas que acceden al sistema de archivos o a redes externas, especialmente si el plugin será usado por múltiples usuarios. Por último, documenta cada herramienta con un docstring descriptivo: el asistente de IA usará esa descripción para decidir cuándo invocar cada función. Con estos pasos, ya tienes un plugin MCP funcional, extensible y listo para integrarse con cualquier asistente compatible.