Tutorial Completo: Transformando APIs de FastAPI en Herramientas Inteligentes con FastAPI-MCP

FastAPI-MCP es un framework que extiende FastAPI para exponer sin problemas tus endpoints de API como herramientas del Protocolo de Contexto de Modelo (MCP). Este tutorial te guiará a través de todo, desde lo básico hasta el uso avanzado de FastAPI-MCP, adecuado tanto para principiantes completos como para desarrolladores experimentados de FastAPI. Cubriremos explicaciones conceptuales, desgloses de componentes, código de ejemplo e ilustraciones basadas en proyectos. Al final, sabrás cómo configurar FastAPI-MCP, configurarlo, asegurarlo con dependencias (autenticación), integrarlo con clientes de IA, desplegarlo y probarlo en escenarios del mundo real.

Introducción a FastAPI-MCP
Primeros Pasos con FastAPI-MCP
Entendiendo las Herramientas y Servicios MCP
Estructurando un Proyecto FastAPI-MCP
Configuración y Personalización
Inyección de Dependencias y Seguridad (Autenticación y Autorización)
Integración con Clientes y Herramientas de IA
Estrategias de Despliegue
Pruebas y Solución de Problemas
Ejemplos del Mundo Real y Casos de Uso
Resumen de Mejores Prácticas
Conclusión
Referencias

Introducción a FastAPI-MCP

FastAPI es un popular framework web de Python para construir APIs rápidamente con documentación OpenAPI automática. MCP (Model Context Protocol), por otro lado, es un estándar abierto emergente que define cómo los asistentes de IA (como GPT-4, Claude de Anthropic, etc.) se comunican con aplicaciones y herramientas. Piensa en MCP como un “puerto USB-C para aplicaciones de IA” – una interfaz universal que permite a los modelos de IA descubrir y usar herramientas externas o fuentes de datos de manera estandarizada. Usando MCP, los modelos de IA pueden:

Descubrir qué herramientas (operaciones de API) están disponibles y qué hacen.
Entender cómo invocar estas herramientas (sus entradas/salidas).
Recuperar datos o ejecutar operaciones a través de estas herramientas de manera unificada.

FastAPI-MCP cierra la brecha entre tus APIs de FastAPI y el ecosistema de herramientas de IA. En términos simples, FastAPI-MCP transformará automáticamente tus endpoints existentes de FastAPI en herramientas compatibles con MCP con un esfuerzo mínimo. Esto significa que puedes exponer tu API a asistentes de IA (como Claude en Cursor IDE, GPT en clientes compatibles, etc.) para que puedan llamar a las operaciones de tu API de forma segura y sin problemas.

¿Por qué usar FastAPI-MCP?

FastAPI-MCP ofrece un enfoque nativo de FastAPI y sin configuración para la integración de IA. No necesitas reescribir tu API ni lidiar con especificaciones complejas de plugins – FastAPI-MCP usa tu aplicación FastAPI existente y construye automáticamente una interfaz MCP sobre ella. Las características clave incluyen:

Integración nativa de dependencias – Puedes asegurar las llamadas a herramientas MCP usando las mismas dependencias Depends() (p. ej., para autenticación) que usas en FastAPI. Esto significa que la lógica de autenticación/autorización existente puede reutilizarse para llamadas iniciadas por IA.
Preservación de esquemas y documentación – Preserva los modelos de solicitud/respuesta y la documentación de tus endpoints, al igual que tu documentación OpenAPI/Swagger. Los agentes de IA obtienen la misma información sobre parámetros y respuestas que los desarrolladores humanos.
Configuración cero/mínima – Simplemente apunta FastAPI-MCP a tu aplicación FastAPI y funciona de inmediato. No se necesita mapeo manual ni decoradores especiales.
Diseño centrado en FastAPI – No es solo un convertidor de OpenAPI; se conecta directamente al sistema de enrutamiento y dependencias de FastAPI para mayor eficiencia y fidelidad.
Soporte de autenticación incorporado – Admite agregar requisitos de autenticación (claves API, OAuth2) para endpoints MCP usando dependencias o configuraciones de FastAPI.
Despliegue flexible – Puedes montar el servidor MCP en la misma aplicación (mismo proceso) o servirlo como un servicio separado; ambos modos son compatibles.
Transporte ASGI eficiente – Por defecto, las llamadas MCP se manejan en proceso a través de ASGI (sin salto HTTP adicional), lo que hace que la comunicación sea rápida y ni siquiera requiera una base_url cuando se co-aloja.

En resumen, FastAPI-MCP hace que sea sencillo convertir tu API en una interfaz accesible para IA. A continuación, nos sumergiremos en cómo configurarlo paso a paso.

Primeros Pasos con FastAPI-MCP

Comencemos desde cero y construyamos una aplicación FastAPI simple, luego habilitemos MCP en ella. Esta sección te guiará a través de la instalación, la configuración básica y la confirmación de que el servidor MCP está funcionando.

Instalación

FastAPI-MCP es un paquete de Python. Puedes instalarlo a través de pip o uv (un gestor de paquetes de Python rápido recomendado por los autores):

# Usando uv (si lo tienes instalado)
uv add fastapi-mcp

# Usando pip
pip install fastapi-mcp

Esto también instalará FastAPI (si no lo está ya) como dependencia. Asegúrate de tener Python 3.10+ (FastAPI-MCP requiere Python 3.10 o posterior). Probablemente también querrás instalar Uvicorn para ejecutar la aplicación, y cualquier otra dependencia de FastAPI que planees usar (como pydantic, etc.). Por ejemplo:

pip install fastapi uvicorn

Ahora estás listo para crear tu aplicación FastAPI e integrar MCP.

Configuración Básica e Implementación

Paso 1: Crea una aplicación FastAPI con un endpoint. Si ya tienes una aplicación FastAPI, puedes usarla; de lo contrario, creemos una mínima. En un archivo (p. ej., main.py), escribe:

from fastapi import FastAPI

app = FastAPI()

# Define un endpoint de ejemplo (operación) como lo harías normalmente
@app.get("/items/{item_id}", operation_id="get_item")
async def read_item(item_id: int):
    """Recupera un artículo por su ID"""
    return {"item_id": item_id, "name": f"Item {item_id}"}

Esto define un endpoint GET simple /items/{item_id} que devuelve un JSON con el ID y el nombre del artículo. Le hemos dado un operation_id="get_item" explícito – este es el nombre que identificará este endpoint como una herramienta MCP (más sobre esto en la siguiente sección). Si no especificas operation_id, FastAPI generará uno automáticamente, pero tiende a ser verboso (p. ej., "read_item_items__item_id__get"), lo cual es menos intuitivo.

Paso 2: Monta FastAPI-MCP en la aplicación. Con FastAPI-MCP, convertir la API anterior en un servidor MCP son solo unas pocas líneas de código. Continuando en main.py:

from fastapi_mcp import FastApiMCP

# ... (Aplicación FastAPI y endpoints como arriba) ...

# Crea una instancia de servidor MCP para nuestra aplicación
mcp = FastApiMCP(
    app,
    name="My API MCP",                  # Nombre opcional para el servicio MCP
    description="MCP server for my API" # Descripción opcional
    # base_url="http://localhost:8000"  # URL base, no requerida si se usa transporte ASGI
)

# Monta el servidor MCP en la aplicación FastAPI
mcp.mount()

¡Eso es todo! Al llamar a FastApiMCP(app) y mcp.mount(), adjuntamos un servicio MCP completamente funcional a nuestra aplicación FastAPI. Proporcionamos un nombre y descripción legibles por humanos para el servidor MCP (estos metadatos ayudan a los clientes a identificarlo), y podríamos especificar una base_url si fuera necesario. Cuando se monta en la misma aplicación, FastAPI-MCP usa llamadas ASGI directas, por lo que base_url es opcional. (Si despliegas el MCP por separado de la API principal, una base_url asegura que el MCP sepa dónde enviar las solicitudes – discutiremos ese escenario más adelante.)

Después de montar, FastAPI-MCP registra automáticamente una nueva ruta (por defecto en la ruta /mcp) en tu aplicación FastAPI. Este es el endpoint al que se conectarán los clientes MCP (agentes o herramientas de IA).

Paso 3: Ejecuta la aplicación. Lanza tu aplicación usando Uvicorn (o tu servidor ASGI preferido):

uvicorn main:app --reload --host 0.0.0.0 --port 8000

Esto inicia la aplicación FastAPI (con nuestra ruta /items/{item_id}) y también el servidor MCP en el endpoint /mcp.

Paso 4: Prueba el endpoint MCP. Abre un navegador (o usa curl) y ve a http://127.0.0.1:8000/mcp. No verás una respuesta JSON típica; en cambio, debido a que MCP usa Server-Sent Events (SSE) para comunicarse, tu navegador podría mantener la conexión abierta y mostrar un flujo de eventos. Por ejemplo, podrías ver algo como:

event: endpoint
data: /mcp/messages/?session_id=abcdef123456...

Esto es normal – indica que el servidor MCP está funcionando y listo. Esencialmente, el endpoint MCP establece inmediatamente una sesión para los clientes a través de SSE. (Si ves datos SSE crudos como arriba, es lo esperado ya que los navegadores no renderizan nativamente los flujos SSE.)

También puedes verificar que tu API original todavía funciona: prueba http://127.0.0.1:8000/items/42 – debería devolver {"item_id": 42, "name": "Item 42"} como de costumbre. La funcionalidad normal de la aplicación FastAPI no cambia; el servidor MCP es un complemento que se ejecuta junto a tu API.

En este punto, con una configuración mínima, tienes un servicio FastAPI habilitado para MCP. Las capacidades de tu API (en este caso, el único endpoint /items/{item_id}) ahora son descubribles e invocables por cualquier agente de IA compatible con MCP. En las siguientes secciones, exploraremos qué se ha expuesto exactamente, cómo personalizarlo y cómo lo usaría un cliente de IA.

Entendiendo las Herramientas y Servicios MCP

Ahora que nuestro servidor MCP está funcionando, aclaremos qué ha creado FastAPI-MCP. Bajo el capó, FastAPI-MCP trata cada operación de API como una Herramienta en términos de MCP, y la colección de herramientas servidas en el endpoint /mcp como un Servicio (servicio de servidor MCP). Aquí hay un desglose de los componentes:

Servidor MCP (Servicio): Este es el servicio que montamos en /mcp. Actúa como una interfaz para los clientes de IA. Cuando un agente de IA se conecta a /mcp (generalmente a través de SSE), puede consultar qué herramientas están disponibles e invocarlas. El servidor MCP se encarga de listar tus endpoints y enrutar las llamadas hacia ellos.
Herramientas MCP: Estas son las operaciones individuales (endpoints) de tu aplicación FastAPI que están expuestas. Cada operación de ruta de FastAPI se convierte en una herramienta con un nombre, descripción, esquema de parámetros de entrada y esquema de salida. Por defecto, FastAPI-MCP nombra cada herramienta según el operation_id del endpoint. En nuestro ejemplo, el endpoint /items/{item_id} tiene operation_id="get_item", por lo que un cliente de IA verá una herramienta llamada "get_item" – sabe que esta herramienta espera un item_id: int y devuelve un objeto de artículo.

Descubrimiento de Herramientas y Documentación

Un aspecto poderoso de FastAPI-MCP es que auto-descubre todos tus endpoints de FastAPI y expone sus metadatos a la IA. Eso incluye: la ruta, el método HTTP, los parámetros de entrada esperados (con tipos/restricciones) y el modelo o esquema de respuesta. Esencialmente, refleja lo que hay en tu documentación OpenAPI. Por ejemplo, si definiste modelos Pydantic para la solicitud o respuesta, esos esquemas se incluyen en la descripción de la herramienta.

Esto significa que un agente de IA puede consultar al servidor MCP (generalmente mediante una solicitud inicial de "listar herramientas") y obtener una lista de nombres y descripciones de herramientas. La descripción de cada herramienta incluye qué hace y cómo usarla. FastAPI-MCP usa el docstring y cualquier descripción que proporcionaste en la ruta de FastAPI como parte de la descripción de la herramienta. Así que si documentaste tu endpoint (como hicimos con un docstring para read_item), la IA lo ve. Una API bien documentada ayuda a la IA a elegir y usar las herramientas correctamente.

IDs de Operación y Nomenclatura de Herramientas: Como se mencionó, los nombres de las herramientas derivan de operation_id. Si no estableces uno, FastAPI generará automáticamente un nombre. Estos nombres autogenerados funcionan, pero a menudo son largos y no son fáciles de usar para humanos. Para los agentes de IA, es beneficioso tener nombres descriptivos y concisos – por lo que es una mejor práctica establecer operation_id para cada endpoint con algo significativo. Por ejemplo, get_user_info para un endpoint que recupera información del usuario (en lugar de un valor predeterminado como read_user_users__user_id__get). Los nombres claros de las herramientas facilitan que una IA decida qué herramienta usar para una tarea determinada.

Si ya tienes una aplicación FastAPI existente sin operation_ids, puedes agregarlos sin cambiar la funcionalidad (solo afectan a la documentación/especificaciones). Como mínimo, asegúrate de que el operation_id de cada endpoint sea único en toda la aplicación.

Cómo los Agentes de IA Usan las Herramientas MCP

Un agente de IA (cliente) conectado a tu servidor MCP típicamente:

Lista las herramientas disponibles – El cliente solicita la lista de herramientas al servidor MCP (esto suele ser un paso automático al conectarse). El servidor MCP responde con los nombres y descripciones de todos los endpoints/herramientas incluidos. El agente ahora sabe lo que puede hacer (p. ej., ve una herramienta get_item que recupera un artículo por ID).
Elige una herramienta y la llama – Cuando el razonamiento de la IA decide realizar una acción (digamos, “obtener el artículo 42”), invocará la herramienta MCP correspondiente. Bajo el capó, esto significa enviar una solicitud a través del protocolo MCP (que FastAPI-MCP traduce en llamar a tu endpoint de FastAPI). Los parámetros de entrada (como item_id=42) se pasan, y FastAPI-MCP llama a la función read_item como una llamada API normal, luego devuelve el resultado al cliente de IA.
Recibe el resultado – La IA obtiene la respuesta del endpoint (aquí, {"item_id": 42, "name": "Item 42"}) a través del canal MCP y puede usarla en su conversación o cómputo. El protocolo asegura que la respuesta esté estructurada (siguiendo el esquema JSON de tu endpoint).

Todo esto sucede de forma segura y en tiempo real. Desde la perspectiva del desarrollador, el código de tu endpoint de FastAPI no cambia en absoluto – FastAPI-MCP se encarga de convertir la llamada a la herramienta de la IA en una llamada de función normal a tu endpoint y de transmitir la respuesta de vuelta.

Importante: MCP usa streaming SSE por defecto para las respuestas, porque algunas salidas de herramientas pueden ser grandes o transmitidas. FastAPI-MCP maneja esto por ti. Si un cliente se conecta a través de SSE, los resultados se envían como eventos. Si un cliente no puede manejar SSE, podría usar un proxy (discutido más adelante). En cualquier caso, como desarrollador de la API, generalmente no necesitas preocuparte por los detalles del streaming – implementa tu endpoint normalmente (devolviendo datos o usando StreamingResponse si ya transmites). FastAPI-MCP lo adaptará a los requisitos de MCP.

Estructurando un Proyecto FastAPI-MCP

Ya sea que estés agregando FastAPI-MCP a un proyecto existente o comenzando uno nuevo, debes organizar tu código de manera mantenible. En demos pequeñas, todo en un archivo está bien, pero para proyectos más grandes considera la siguiente estructura:

myproject/
├── app.py          # Aplicación FastAPI y definiciones de rutas API
├── mcp_app.py      # (Opcional) Aplicación FastAPI separada para MCP si se despliega por separado
├── routes/         # Paquete para módulos de ruta, si divides tus endpoints
│   ├── __init__.py
│   └── items.py    # p. ej., define endpoints /items
├── models/         # Modelos de datos (modelos Pydantic, etc.)
├── auth/           # Utilidades de autenticación (si las hay)
└── ... (otros módulos)

Configuración de aplicación única: Si planeas servir el MCP en la misma instancia de aplicación que tu API (que es lo más simple), puedes integrarlo en el código de tu aplicación principal. Por ejemplo, en app.py después de definir todas tus rutas, instancias FastApiMCP(app) y llamas a mcp.mount(). A menudo es prudente crear el MCP después de que se hayan agregado todas tus rutas, para que capture cada endpoint. De esta manera, no tienes que “refrescar” el MCP cuando se agregan nuevas rutas (más sobre refrescar en un momento).

Configuración de aplicación separada (estilo microservicio): En algunos casos, es posible que desees ejecutar el servidor MCP como un servicio separado de la API principal. FastAPI-MCP admite eso permitiéndote montar el MCP en una aplicación FastAPI diferente. Por ejemplo:

# archivo: api_app.py
from fastapi import FastAPI
api_app = FastAPI()
# ... define todos tus endpoints API en api_app ...

# archivo: mcp_app.py
from fastapi import FastAPI
from fastapi_mcp import FastApiMCP
from api_app import api_app  # importa la otra aplicación FastAPI

mcp_app = FastAPI()                 # aplicación separada solo para MCP
mcp = FastApiMCP(api_app)           # crea MCP desde la aplicación API
mcp.mount(mcp_app)                  # monta las rutas MCP en la aplicación separada

Aquí tenemos dos instancias de FastAPI: api_app (con nuestros endpoints regulares) y mcp_app (que solo sirve la interfaz MCP). Pasamos api_app a FastApiMCP y lo montamos en mcp_app. Luego ejecutaríamos estas dos aplicaciones por separado (p. ej., uvicorn api_app:api_app en un host/puerto y uvicorn mcp_app:mcp_app en otro). El servidor MCP llamará internamente a la otra aplicación. En este escenario, dado que son procesos separados, deberías establecer la base_url en FastApiMCP para que apunte al host de la API (o proporcionar un cliente HTTP personalizado) para que el MCP sepa cómo llegar a la aplicación API. Alternativamente, puedes ejecutarlos en el mismo proceso montando una aplicación dentro de la otra, pero eso es menos común.

¿Qué configuración elegir? Para muchos casos, montar MCP en la misma aplicación (quizás bajo la ruta /mcp) está perfectamente bien y es más simple. Mantiene todo en un solo servicio para desplegar. Sin embargo, el despliegue separado podría ser útil si:

Quieres escalar o asegurar la interfaz MCP de forma independiente. Por ejemplo, si el servicio MCP es para uso interno por agentes de IA, podrías alojarlo en una red interna separada de la API principal.
Quieres ejecutar el servidor MCP en un puerto o dominio diferente (quizás debido a requisitos de SSE o del cliente).
Tu API es muy sensible al rendimiento y prefieres aislar la sobrecarga de MCP (aunque MCP es ligero).

La flexibilidad de FastAPI-MCP significa que puedes comenzar montándolo junto (por conveniencia de desarrollo) y luego dividirlo sin cambiar el código de tu endpoint – solo ajusta cómo creas y montas el servidor MCP.

Consejos de estructura de proyecto: Mantén tu aplicación FastAPI modular (usa routers, archivos separados para la lógica), ya que FastAPI-MCP solo necesita el objeto final de la aplicación FastAPI. Si agregas nuevas rutas después de configurar MCP (por ejemplo, dinámicamente o en un entorno interactivo), necesitarás refrescar el servidor MCP para que las recoja (a través de mcp.setup_server() que vuelve a escanear los endpoints). En una aplicación estática típica, solo asegúrate de que todas las rutas estén definidas antes de montar MCP. Si alguna vez lo olvidas y tus nuevas herramientas no aparecen, puedes llamar a mcp.setup_server() o recrear la instancia de MCP.

Configuración y Personalización

FastAPI-MCP funciona sin configuración por defecto, pero proporciona varias opciones para personalizar el comportamiento del servidor MCP y las herramientas expuestas. Aquí discutiremos cómo configurar los metadatos del servidor, mejorar la documentación de las herramientas y filtrar qué endpoints se exponen.

Metadatos del Servidor (Nombre y Descripción)

Al crear FastApiMCP, puedes pasar un name y description para tu servicio MCP. Estos ayudan a identificar tu servicio a los clientes. Por ejemplo:

mcp = FastApiMCP(app, 
                 name="Inventory API MCP", 
                 description="Interfaz MCP para mi API de Inventario")

En el protocolo MCP, el servidor puede presentar un nombre/descripción que los clientes podrían mostrar en una interfaz. Es opcional pero se recomienda establecerlo, especialmente si ejecutas múltiples servicios MCP. Por defecto, si no se establece, puede usar un nombre genérico. Establecer una descripción clara (p. ej., “Endpoints para gestionar artículos de inventario”) puede guiar a los agentes de IA o desarrolladores sobre el propósito del servicio.

Descripciones de Herramientas y Esquemas de Respuesta

FastAPI-MCP utiliza automáticamente tu documentación de FastAPI (descripciones de operaciones de ruta, documentación de esquemas Pydantic, etc.) para describir cada herramienta. Si deseas proporcionar descripciones aún más ricas para la IA, FastAPI-MCP ofrece indicadores para incluir más detalles del esquema:

describe_all_responses=True: incluye la documentación de todos los posibles códigos de respuesta y esquemas para el endpoint en la descripción de la herramienta. Normalmente, la descripción de una herramienta podría centrarse en la respuesta de éxito principal; con esto, si tienes múltiples modelos de respuesta (p. ej., respuestas de error), también se describirán.
describe_full_response_schema=True: incluye el esquema JSON completo del modelo de respuesta en la descripción de la herramienta. Esto puede ser muy útil para que los agentes de IA comprendan completamente la estructura de la salida. Por ejemplo, si tu endpoint devuelve un JSON anidado, la IA conocerá los campos y tipos exactos esperados.

Puedes habilitar estos al instanciar FastApiMCP:

mcp = FastApiMCP(app,
                 describe_all_responses=True,
                 describe_full_response_schema=True)

Ten en cuenta que las descripciones extremadamente verbosas pueden o no ayudar a un modelo de IA – podría ser beneficioso para la precisión, pero algunos clientes podrían truncar descripciones muy largas. Usa estos indicadores según sea necesario, especialmente si tus endpoints tienen salidas complejas de las que la IA debería estar al tanto.

Filtrado de Endpoints (Exposición Selectiva)

En muchos casos, es posible que no quieras exponer todos los endpoints de la API a los agentes de IA. Por ejemplo, una aplicación podría tener endpoints internos o de administración que no son seguros para que los use una IA, o simplemente no son relevantes. FastAPI-MCP te permite incluir o excluir endpoints usando sus IDs de operación o etiquetas.

Tienes cuatro parámetros opcionales principales para filtrar herramientas:

include_operations: una lista de IDs de operación a incluir. Solo estos se convertirán en herramientas MCP (todos los demás se ignoran).
exclude_operations: una lista de IDs de operación a excluir (todo lo demás se incluirá).
include_tags: solo incluye endpoints que tengan alguna de estas etiquetas FastAPI. Si organizas tus rutas por etiquetas (p. ej., tags=["public"]), podrías exponer solo las “públicas”.
exclude_tags: excluye endpoints que tengan alguna de estas etiquetas.

Nota: No puedes mezclar inclusión y exclusión del mismo tipo – por ejemplo, no puedes usar include_operations y exclude_operations juntos. Sin embargo, puedes combinar filtros de operación con filtros de etiqueta. La lógica al combinar es unión codiciosa: los endpoints que coinciden con cualquier criterio de inclusión se incluyen, luego se eliminan los que coinciden con cualquier criterio de exclusión.

Ejemplos:

Exponer solo endpoints específicos:
```
mcp = FastApiMCP(app, include_operations=["get_item", "list_items"])
```
Esto expondría solo las herramientas llamadas get_item y list_items (y ningún otro endpoint).
Excluir un endpoint peligroso:
```
mcp = FastApiMCP(app, exclude_operations=["delete_item"])
```
Esto expone todos los endpoints excepto el que tiene operation_id “delete_item”. Útil si quieres bloquear ciertas operaciones (como eliminación o acciones sensibles) del uso de IA.
Por etiquetas: Supongamos que etiquetas ciertas rutas como admin o internal. Entonces:
```
mcp = FastApiMCP(app, exclude_tags=["admin", "internal"])
```
expondría todo excepto los endpoints marcados con esas etiquetas (asegurando que las APIs internas no estén disponibles para la IA).
Combinado: Si quieres incluir solo ciertas etiquetas pero también excluir una operación específica dentro de ellas, podrías hacer:
```
mcp = FastApiMCP(app, include_tags=["public"], exclude_operations=["reset_database"])
```
Esto tomaría todos los endpoints etiquetados como "public" y los expondría, excepto cualquiera cuyo operation_id sea "reset_database" incluso si tuviera esa etiqueta.

Usando el filtrado, puedes ajustar la superficie de tu API que es accesible para la IA. Una estrategia común es exponer solo operaciones de solo lectura o seguras y excluir cualquier cosa que modifique datos o realice acciones críticas (especialmente si tu servidor MCP podría ser accedido por agentes de IA no confiables). Esto nos lleva a las consideraciones de seguridad que cubriremos a continuación.

Refrescando Herramientas ante Cambios

Si tu aplicación es de larga duración y agregas rutas dinámicamente (quizás montando nuevos routers en tiempo de ejecución u otros sistemas de plugins), recuerda que la lista de herramientas de FastAPI-MCP se construye cuando llamas a mcp.mount() (o setup_server()). Los nuevos endpoints agregados más tarde no aparecerán automáticamente hasta que refresques. Tienes dos formas de manejar esto:

Define todas las rutas primero, luego crea el servidor MCP. En el inicio normal, simplemente ordena tu código de tal manera que termines de agregar rutas a app antes de llamar a FastApiMCP(app) y mount(). Este es el enfoque más simple y evita cualquier problema.
Refresca manualmente si es necesario. Si debes agregar una ruta después de montar MCP, llama a mcp.setup_server() después para volver a escanear y registrar el nuevo endpoint. Alternativamente, podrías reinicializar FastApiMCP (pero setup_server() es más fácil). La FAQ señala este requisito: los endpoints agregados después de la creación no se ven hasta que se vuelven a registrar las herramientas.

En desarrollo, es fácil olvidarlo – si no ves una herramienta que esperas, verifica si el MCP se creó demasiado pronto. El log o la salida SSE también podrían advertir que no se encontraron herramientas si eso sucede.

Inyección de Dependencias y Seguridad (Autenticación y Autorización)

Asegurar tu API cuando es accedida por IA es crucial. FastAPI-MCP te permite aprovechar el sistema de inyección de dependencias de FastAPI para aplicar autenticación u otras verificaciones en las llamadas MCP, tal como lo harías en llamadas API normales. En otras palabras, puedes aplicar OAuth2, autenticación por clave API, verificaciones de permisos, etc., a la interfaz MCP para que solo se permita el acceso autorizado.

Usando Dependencias de FastAPI para Autenticación

Los endpoints de FastAPI a menudo usan dependencias (a través de Depends(), Security(), etc.) para la autenticación. Por ejemplo, podrías tener:

from fastapi import Depends, HTTPException
from fastapi.security import OAuth2PasswordBearer

oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")

@app.get("/users/me")
async def get_current_user(token: str = Depends(oauth2_scheme)):
    user = verify_token_and_get_user(token)
    if not user:
        raise HTTPException(status_code=401, detail="Token inválido o expirado")
    return {"username": user.username}

Si expones tal endpoint a través de MCP, un cliente de IA necesitaría suministrar el encabezado Authorization (con un token Bearer) para usarlo. FastAPI-MCP respetará todas las dependencias en el endpoint original. Esto significa que si la dependencia lanza una HTTPException (p. ej., 401), la llamada MCP también resultará en un error (y la IA recibirá un fallo).

Sin embargo, no todos los clientes de IA pueden proporcionar fácilmente tokens de autenticación de forma predeterminada. Muchos clientes MCP actuales son IDEs o agentes que podrían no conocer tu autenticación. Para manejar esto, FastAPI-MCP proporciona un argumento auth_config o un argumento dependencies más simple que puede aplicar la autenticación en la capa MCP y facilitar el paso de tokens.

Autenticación Básica por Clave API o Token

La forma más simple de asegurar el servidor MCP es requerir una clave API para todas las llamadas a herramientas. Puedes hacer esto agregando una dependencia a FastApiMCP que verifique un encabezado. Por ejemplo, usando un encabezado de clave API:

from fastapi import Security, HTTPException
from fastapi.security import APIKeyHeader

api_key_header = APIKeyHeader(name="X-API-Key")

async def verify_api_key(key: str = Security(api_key_header)):
    if key != "mysecret123":
        raise HTTPException(status_code=403, detail="Clave API inválida")
    return True

mcp = FastApiMCP(app, 
    # asegura que cada solicitud MCP dependa de verify_api_key
    auth_config=AuthConfig(dependencies=[Depends(verify_api_key)])
)
mcp.mount()

Ahora, cualquier llamada a una herramienta a través de la interfaz MCP requerirá el encabezado X-API-Key: mysecret123. Si el encabezado falta o es incorrecto, la solicitud MCP será rechazada con 403 Prohibido. Esencialmente, esto agrega una dependencia global al propio servidor MCP.

Nota: En ejemplos más antiguos o uso más simple, podrías ver FastApiMCP(app, mcp_dependencies=[Depends(verify_api_key)]) que logra el mismo efecto. El enfoque más reciente lo envuelve en AuthConfig para opciones más avanzadas. De cualquier manera, el concepto es el mismo: FastAPI-MCP puede usar una dependencia para proteger las herramientas.

Para un esquema de clave API, el cliente de IA necesita enviar ese encabezado. Si estás usando una herramienta como mcp-remote o un cliente personalizado, puedes configurarlo para incluir encabezados en cada solicitud. Por ejemplo, usando mcp-remote (un cliente proxy basado en Node), se puede pasar un encabezado como:

"mcpServers": {
  "myapi": {
    "command": "npx",
    "args": ["mcp-remote", "http://localhost:8000/mcp", "--header", "X-API-Key:mysecret123"]
  }
}

Esto asegura que el encabezado se adjunte a cada llamada, satisfaciendo la dependencia.

Autenticación OAuth2

FastAPI-MCP también admite el flujo completo de código de autorización OAuth2 como se especifica en la especificación MCP (2025-03-26). Esto es más complejo pero permite un inicio de sesión OAuth impulsado por el usuario si el cliente lo admite. En la práctica, hasta ahora muchos clientes MCP no admiten completamente los flujos OAuth interactivos, por lo que usar un token API o una clave API (como arriba) podría ser más sencillo. Si necesitas OAuth2, puedes configurar AuthConfig con ajustes OAuth como emisor, URL de autorización, URL de token, etc. Por ejemplo:

mcp = FastApiMCP(app, auth_config=AuthConfig(
    issuer="https://auth.example.com/",
    authorize_url="https://auth.example.com/authorize",
    oauth_metadata_url="https://auth.example.com/.well-known/oauth-authorization-server"
))

Esto anunciaría al cliente MCP los detalles de OAuth. La idea es que el agente de IA (o el usuario que lo controla) pueda obtener un token a través de OAuth para usar las herramientas. En la práctica, hasta que las herramientas del cliente de IA se pongan al día, podrías depender del paso de tokens o claves API.

Consejo: Puedes combinar enfoques: por ejemplo, permitir el paso básico de tokens y también tener una dependencia de autenticación que verifique un token válido. La documentación oficial sugiere que si simplemente pasas un encabezado Authorization: Bearer <token> desde el cliente, FastAPI-MCP lo reenviará a los endpoints de FastAPI. Así que si tus endpoints ya esperan un token bearer a través de Depends(oauth2_scheme), funcionará siempre que el cliente lo suministre. Usar mcp-remote --header Authorization:Bearer <token> es una forma de asegurar eso.

Otros Usos de la Inyección de Dependencias

Aparte de la autenticación, tus endpoints podrían usar dependencias para otras cosas (sesión de base de datos, etc.). La buena noticia es que todas esas siguen funcionando normalmente. FastAPI-MCP llama a tu endpoint a través de la aplicación FastAPI, por lo que dependencias como db: Session = Depends(get_db) se ejecutarán como de costumbre. No hay diferencia entre una llamada activada por IA y una llamada HTTP regular en términos de cómo se ejecuta el código de tu endpoint – se aplica la misma inyección de dependencias y contexto.

Una cosa a tener en cuenta: si una dependencia espera cierto contexto (como un objeto de solicitud o encabezados especiales), asegúrate de que el cliente MCP los proporcione o que tu dependencia pueda manejar cuando falten. Por ejemplo, las dependencias que dependen de Request podrían comportarse de manera diferente bajo MCP ya que la “solicitud” es la llamada MCP. Pero en la mayoría de los casos, no es un problema.

Mejores Prácticas de Seguridad: Al exponer tu API a la IA a través de MCP, considera estas pautas (similares a la seguridad API normal, pero con la imprevisibilidad de los agentes de IA en mente):

Expón solo endpoints seguros: Prefiere operaciones de solo lectura o idempotentes. Sé muy cauteloso al exponer cualquier cosa que modifique datos o realice acciones irreversibles. Si lo haces, asegúrate de que se requiera autenticación y tal vez incluso un paso de aprobación fuera de MCP.
Requiere autenticación para operaciones sensibles: No confíes en la oscuridad. Si un endpoint devuelve datos sensibles, protégelo con la autenticación adecuada incluso si piensas que “solo la IA” lo sabe. Los listados de MCP podrían ser accesibles para cualquier cliente con acceso. Usa claves API u OAuth según corresponda.
Valida las entradas estrictamente: Tus endpoints ya deberían hacer esto (usando modelos Pydantic, sugerencias de tipo). Esto es extra importante cuando el llamador es una IA que podría cometer errores. La validación robusta evita que la IA pase accidentalmente datos inválidos o realice algo no intencionado.
Sanitiza las salidas si es necesario: Si ciertos datos deben ser parcialmente enmascarados o procesados antes de devolverlos (por privacidad o seguridad), asegúrate de que tu endpoint lo haga. No asumas que la IA manejará la confidencialidad – es mejor que los datos que salen de tu servidor sean seguros.
Monitorea el uso: Mantén logs de cuándo se llaman las herramientas y con qué parámetros. Monitorear cómo la IA usa tu API puede ayudar a identificar el mal uso o las mejoras necesarias. Podrías detectar patrones como una IA llamando a un endpoint con demasiada frecuencia o con parámetros extraños, lo que podría indicar un malentendido que puedes abordar ajustando las descripciones o agregando restricciones.

Al usar la robusta inyección de dependencias y el modelo de seguridad de FastAPI, FastAPI-MCP te permite aplicar todas estas medidas para el acceso de IA tal como lo harías para el acceso humano.

Integración con Clientes y Herramientas de IA

Una vez que tu servidor FastAPI-MCP esté en funcionamiento y asegurado apropiadamente, el siguiente paso es usarlo realmente con un cliente de IA. Hay algunas formas en que los sistemas de IA pueden conectarse a tu servicio MCP:

Conexión SSE Directa: Muchos IDEs de IA o frameworks de agentes soportan MCP nativamente vía SSE.
Proxy o Puente (mcp-remote): Un pequeño proxy que maneja SSE y características avanzadas, útil si el cliente no soporta SSE o necesitas inyectar autenticación.
Herramientas de Inspección o Pruebas: Útiles para pruebas manuales y depuración de tu interfaz MCP.
Integración Personalizada (LangChain o código personalizado): Puedes escribir código para conectarte a un servidor MCP también, aunque las bibliotecas para esto son incipientes.

Exploremos los métodos comunes.

Conexión vía Server-Sent Events (Directa)

Los servidores MCP (como FastAPI-MCP) usan fundamentalmente Server-Sent Events para la comunicación. Herramientas como Cursor IDE, Claude Desktop, Windsurf, extensiones de VSCode y otras han comenzado a soportar MCP permitiéndote configurar un endpoint MCP.

Por ejemplo, en Cursor (IDE de asistente de codificación IA), puedes agregar tu servidor MCP en sus ajustes. Podría implicar editar un archivo de configuración mcp.json para incluir tu servidor. Según una guía, agregarías algo como:

{
  "mcpServers": {
    "fastapi-mcp": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

Aquí "fastapi-mcp" es solo una etiqueta que le das, y la url apunta a tu endpoint FastAPI-MCP en ejecución. En Cursor, irías a Settings → MCP → Add new MCP server e ingresarías la URL. Una vez configurado, el cliente se conectará (a menudo inmediatamente o cuando abras un chat de IA) a tu servidor MCP.

¿Qué sucede después? Típicamente, el IDE o cliente listará ahora nuevas “herramientas” o capacidades. En el caso de Cursor, podrías ver en la interfaz del agente que las herramientas de tu API (como get_item) están disponibles para que la IA las use. El modelo de IA (con alguna ingeniería de prompt del sistema) es consciente de estas herramientas. Ahora puedes pedirle a la IA que las use. Por ejemplo, podrías indicar: “Usa la herramienta get_item para obtener el artículo 42.” La IA, a través de la integración MCP, llamará a la herramienta y devolverá el resultado en su respuesta.

Para ilustrar, después de configurar, uno podría simplemente preguntarle a la IA (en la pestaña del agente de Cursor): “Llama al endpoint /items/42 por mí.” La IA detectaría que corresponde a la herramienta get_item y la ejecutaría, luego probablemente respondería con los datos. Esto es increíblemente poderoso – la IA actúa efectivamente como un intermediario para tu API, permitiendo interacciones conversacionales o autónomas con tu servicio.

La mayoría de los clientes modernos conscientes de MCP usan SSE, por lo que la conexión directa suele ser la más simple. Asegúrate de que la URL de tu servidor MCP sea accesible para el cliente (si estás ejecutando ambos localmente, localhost está bien; si la IA es remota, necesitarías exponer una URL que la IA pueda alcanzar).

Usando un Proxy MCP (para Autenticación o Clientes Incompatibles)

No todos los clientes de IA soportan SSE o encabezados personalizados. Por ejemplo, Claude Desktop de Anthropic (en versiones anteriores) no soportaba SSE nativamente para MCP, y algunas herramientas podrían no permitirte agregar encabezados de autenticación personalizados fácilmente. En estos casos, la solución recomendada es usar mcp-remote (también referido como mcp-proxy en algunas documentaciones). Este es un paquete npm que esencialmente actúa como un puente: se conecta a tu servidor MCP vía SSE por un lado, y ofrece una interfaz local stdio o WebSocket por el otro lado que el cliente de IA puede usar.

Por ejemplo, podrías configurar una entrada de cliente MCP como:

{
  "mcpServers": {
    "myapi-via-proxy": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:8000/mcp",
        "8080"
      ]
    }
  }
}

Esto le diría al sistema que ejecute npx mcp-remote http://localhost:8000/mcp 8080. Este comando se conecta a tu endpoint MCP y abre un puerto local 8080 que la IA puede usar. La IA entonces se conectaría realmente al proxy (que podría presentarse como un servidor MCP sin restricciones SSE). El proxy retransmite las solicitudes a tu servicio FastAPI-MCP real y canaliza las respuestas de vuelta.

Puedes también pasar encabezados a través de mcp-remote, como se mostró antes, usando --header "Authorization:Bearer XYZ" o similar, lo cual es muy útil para la autenticación. Esencialmente, mcp-remote puede inyectar esos encabezados por ti en cada llamada, para que el cliente no necesite saber sobre ellos.

Usa mcp-remote si:

Tu cliente no soporta proporcionar los encabezados de autenticación requeridos o no soporta SSE.
Quieres ejecutar la IA en un entorno donde una conexión de puerto local es más fácil que SSE (algunos casos por razones de firewall o compatibilidad).
Necesitas depurar o registrar el tráfico – ejecutar un proxy puede permitirte ver las solicitudes yendo y viniendo.

mcp-remote es una herramienta Node, así que necesitas Node.js disponible en el entorno donde se ejecuta el cliente de IA. La sobrecarga suele ser baja.

Inspector MCP (Pruebas Manuales)

Antes de involucrar a una IA en absoluto, podrías querer probar manualmente tu servidor MCP para ver qué herramientas expone y asegurarte de que funcionan. El Inspector MCP es una utilidad de línea de comandos para este propósito, proporcionada por el proyecto Model Context Protocol. Puedes ejecutarlo con npx también:

npx @modelcontextprotocol/inspector

Esto iniciará un prompt interactivo (probablemente en un navegador) donde puedes ingresar la URL de tu servidor MCP e inspeccionarlo. Pasos para usarlo:

Asegúrate de que tu servidor FastAPI-MCP esté funcionando.
Ejecuta el inspector (npx @modelcontextprotocol/inspector).
Cuando se te solicite, ingresa la URL del endpoint MCP (p. ej., http://localhost:8000/mcp).
El inspector listará las Herramientas disponibles. Puedes seleccionar una herramienta y completar los parámetros para probar llamarla, luego haz clic en "Run Tool".
Verás la respuesta y podrás confirmar que todo está conectado correctamente.

Esto es esencialmente como una UI de Swagger pero para MCP. Es muy útil para confirmar que tus endpoints aparecen como se espera y que la autenticación está funcionando (si configuraste autenticación, podrías necesitar proporcionar encabezados en el inspector – tiene opciones para agregar encabezados también).

Integración vía Código (LangChain o Personalizado)

¿Qué pasa si quieres construir tu propio agente de IA en Python que use el servidor MCP? Aunque podrías usar directamente un cliente HTTP para conectarte a /mcp y manejar SSE, eso es un poco de bajo nivel. Hay bibliotecas emergentes para ayudar. Por ejemplo, el repositorio GitHub de fastapi-mcp menciona un cliente MCP y herramientas para componer servidores. También hay un proyecto llamado FastMCP (jlowin/fastmcp) que puede construir clientes MCP e incluso componer múltiples servidores MCP.

En este momento, estos son temas avanzados, pero un enfoque de ejemplo podría ser:

Usar httpx o requests de Python para iniciar una solicitud GET a /mcp con stream=True para manejar eventos SSE.
Analizar el evento inicial "endpoint" para obtener la sesión o el endpoint de control (a menudo el protocolo implica un mensaje inicial con una URL de messages).
Enviar un comando para listar herramientas (la especificación MCP define un mensaje para eso) y analizar la respuesta.
Invocar una herramienta específica enviando la carga útil JSON apropiada como un evento o solicitud.

Esto está más allá del alcance de este tutorial, pero ten en cuenta que, dado que MCP es un estándar abierto (hay una especificación oficial y SDKs), podrías integrar a ese nivel si fuera necesario. Por ejemplo, una integración con LangChain podría tratar al servidor MCP de manera similar a como trata la llamada de funciones o herramientas de OpenAI – se necesitaría un adaptador para traducir una “herramienta” de LangChain a una llamada de herramienta MCP. Podríamos ver bibliotecas de primera clase para la integración de MCP en Python pronto, a medida que crece el ecosistema.

Por ahora, usar clientes de IA existentes o el inspector es la forma más fácil de trabajar con tu servidor MCP.

Estrategias de Despliegue

Desplegar una aplicación FastAPI-MCP es muy similar a desplegar cualquier aplicación FastAPI. Debido a que es solo una aplicación ASGI, puedes usar Uvicorn, Hypercorn o Gunicorn (con workers Uvicorn) para ejecutarla, y contenerizarla con Docker si lo deseas. Sin embargo, ten en cuenta las consideraciones de SSE y de red:

Despliegue en la misma aplicación: Si montas MCP en la misma aplicación FastAPI, desplegarás un solo servicio. Asegúrate de que el entorno pueda soportar SSE (la mayoría de los servidores ASGI lo hacen – Uvicorn lo hace de forma predeterminada). Si está detrás de un proxy inverso (como Nginx), configúralo para no almacenar en búfer los flujos SSE y para permitir conexiones keep-alive.
Despliegue separado: Si divides la API y MCP en servicios separados, desplegarás dos aplicaciones. Asegúrate de que el servicio MCP sepa cómo alcanzar el servicio API (a través de base_url o red interna). Por ejemplo, podrías desplegar tu API principal en api.example.com y el MCP en mcp.example.com, con la base_url del http_client del MCP establecida en https://api.example.com. También podrían comunicarse a través de una dirección interna si están coubicados.

Ejemplo (Despliegue Separado con Docker Compose): Podrías tener dos contenedores, uno para la API y otro para MCP. El contenedor MCP podría tener una variable de entorno para la URL de la API. Usar FastApiMCP(app, http_client=httpx.AsyncClient(base_url=os.getenv("API_URL"))) dirigiría las llamadas al servicio API. De esta manera, el contenedor MCP no necesita el código de la API importado – incluso podría llamar a un servicio completamente diferente siempre que tenga un OpenAPI compatible (aunque típicamente simplemente importarías la misma aplicación FastAPI como mostramos antes).

Escalado: Si tu API es pesada y solo esperas un uso moderado de MCP (o viceversa), puedes escalarlos independientemente. Por ejemplo, ejecuta múltiples réplicas de la API detrás de un balanceador de carga, y quizás solo se necesiten una o dos instancias de servidor MCP para el uso de IA. Debido a que MCP usa streaming, podrías no poner un balanceador de carga frente al MCP (para evitar romper SSE), o usar una estrategia de conexión persistente (sticky connection).

HTTPS y Redes: Si el cliente de IA se conectará desde un servicio externo (digamos, un IDE en línea o un agente ejecutándose en la nube), necesitarás servir tu endpoint MCP sobre HTTPS (por seguridad, y porque muchos clientes pueden requerirlo). Esto típicamente significa ponerlo detrás de un proxy que termine SSL o usar un servicio en la nube. No hay nada específico de MCP sobre esto – trátalo como exponer un endpoint API. Usa TLS adecuado, nombres de dominio, etc. Si tu MCP es solo para uso interno, podrías no exponerlo públicamente en absoluto.

Refrescado y Actualizaciones: Si actualizas tu API con nuevos endpoints, recuerda volver a desplegar o refrescar el servicio MCP para que sepa sobre los nuevos endpoints. Si el servicio MCP es de larga duración, un reinicio gradual o llamar a setup_server() (quizás activado por un script de despliegue) podría usarse para recoger los cambios.

En resumen, despliega FastAPI-MCP como lo harías con un microservicio FastAPI. La principal diferencia es asegurar que SSE funcione de extremo a extremo y planificar si es parte de tu aplicación principal o un servicio independiente. La documentación oficial tiene un ejemplo simple que muestra procesos uvicorn separados en diferentes puertos, pero puedes adaptar eso a cualquier infraestructura.

Pruebas y Solución de Problemas

Probar una configuración de FastAPI-MCP implica verificar tanto el comportamiento tradicional de la API como la nueva interfaz MCP. Aquí hay algunas estrategias:

Probando los Endpoints de la API

Primero, continúa escribiendo pruebas para tus endpoints de FastAPI como de costumbre (usando TestClient de FastAPI o llamadas HTTP). FastAPI-MCP no cambia la lógica de tus endpoints, por lo que las pruebas unitarias y de integración para ellos siguen siendo válidas. Asegurar que cada endpoint devuelva los datos esperados dadas las entradas asegurará indirectamente que la salida MCP también sea correcta.

Probando la Interfaz MCP

Para probar específicamente la capa MCP, puedes simular un cliente MCP. Como se mencionó, la herramienta MCP Inspector es excelente para pruebas manuales – es como un cliente de prueba interactivo. Úsala durante el desarrollo para asegurarte de que todas tus herramientas estén listadas y funcionando:

Ejecuta tu aplicación, conecta el inspector, lista las herramientas. Si algo debería estar allí y no lo está, verifica los IDs de operación y si llamaste a mount() después de definir esas rutas.
Usa el inspector para llamar a cada herramienta con entradas válidas e inválidas. Por ejemplo, prueba un parámetro requerido faltante y ve que devuelve un error de validación (tal como lo haría tu API a través de la validación de FastAPI). El inspector mostrará la respuesta de error.

Para pruebas automatizadas, podrías escribir una pequeña prueba que use el cliente SSE de Python o websockets para conectarse a /mcp. Python no tiene soporte SSE incorporado, pero podrías usar httpx con un analizador de event-stream. Sin embargo, esto puede complicarse. Otro enfoque es ejecutar un comando como npx @modelcontextprotocol/inspector o mcp-remote en un entorno de prueba para asegurar que la conexión funcione (aunque eso sale de las pruebas puras de Python).

Si tus endpoints son simples, una verificación pragmática es ver que GET http://localhost:8000/mcp devuelve un 200 y produce un flujo de eventos (podrías analizar el primer evento). Por ejemplo:

from fastapi.testclient import TestClient

client = TestClient(app)
response = client.get("/mcp", stream=True)
assert response.status_code == 200
chunks = []
for chunk in response.iter_content(chunk_size=None):
    chunks.append(chunk.decode())
    if b"event: " in chunk:
        break
stream_output = "".join(chunks)
assert "event: endpoint" in stream_output or "event: tool_list" in stream_output

Esto es un poco rudimentario pero verifica que el endpoint MCP produce un evento. Una prueba más exhaustiva simularía un cliente MCP y realizaría el comando de listado de herramientas.

Consejos para Solucionar Problemas

“No hay herramientas MCP disponibles”: Si el cliente de IA dice que no encontró herramientas, probablemente el servidor MCP no registró ningún endpoint. Asegúrate de que FastApiMCP(app) se llamó después de configurar las rutas (o llama a setup_server() para refrescar). También asegúrate de no haber filtrado todo por accidente con la configuración de inclusión/exclusión.
Problemas de autenticación: Si proteges el MCP con autenticación y el cliente de IA no puede conectarse, verifica que el cliente esté enviando el encabezado o token. Podrías probar usando curl con el encabezado para ver si obtienes un 200 OK en /mcp. Ejemplo: curl -N http://localhost:8000/mcp -H "X-API-Key: mysecret123" (el -N es para no almacenar en búfer la salida, para que veas SSE). Si esto funciona, entonces el problema es la configuración del cliente.
La conexión SSE se cierra inmediatamente: Esto podría suceder si ocurre un error al conectar. Revisa los logs de tu servidor; si tu dependencia de autenticación lanzó un error debido a un token faltante, la conexión podría caerse. O si se lanza una excepción durante el listado de herramientas. Los logs generalmente indicarán la causa.
La llamada a la herramienta no funciona: Si una IA dice que intentó usar una herramienta pero obtuvo un error, trátalo como un error de llamada API. Por ejemplo, la IA podría proporcionar una cadena donde se espera un entero, causando un error de validación 422. Estos errores se envían de vuelta a través de MCP como eventos – revisa los logs o usa el inspector para replicar la llamada. Es posible que necesites ajustar tus descripciones para que la IA conozca los tipos correctos.
Rendimiento: Si las llamadas son lentas, recuerda que con SSE la conexión permanece abierta. Asegúrate de no estar haciendo algo como leer el cuerpo de la solicitud de una manera que se detenga. Usualmente no es un problema, pero si usas respuestas de streaming, asegúrate de producir los datos correctamente. Para un alto rendimiento, considera el escalado horizontal.
Desajustes de la especificación MCP: Como MCP está evolucionando, podría haber ligeras diferencias de versión entre clientes y servidor. FastAPI-MCP tiene como objetivo estar actualizado con la especificación. Si encuentras una incompatibilidad con un cliente en particular, revisa las notas de la versión de FastAPI-MCP. Una solución alternativa a menudo puede ser usar mcp-remote ya que tiende a normalizar la comunicación.

Probando metódicamente tanto la API como la interfaz MCP, puedes tener confianza en tu despliegue. Es aconsejable probar con el cliente de IA real que esperas usar (p. ej., si tu objetivo son los usuarios de Cursor IDE, prueba con Cursor; si es Claude Desktop, prueba a través de Claude con mcp-remote).

Ejemplos del Mundo Real y Casos de Uso

FastAPI-MCP abre muchas posibilidades para integrar APIs con IA. Aquí hay algunos escenarios para ilustrar aplicaciones prácticas:

Asistente de Documentación Impulsado por IA: Expón tus endpoints públicos de API a través de MCP para que un asistente de IA pueda ayudar a los usuarios a explorar la API. Por ejemplo, un usuario podría preguntar “¿Cómo creo un nuevo usuario con esta API?” y la IA (teniendo acceso a las herramientas MCP) podría encontrar el endpoint create_user e incluso ejecutar llamadas de ejemplo. Esto proporciona una experiencia de documentación interactiva impulsada por IA.
Asistente Interno para Desarrolladores: Dentro de una empresa, los desarrolladores podrían tener un agente de IA (en VSCode o Slack) conectado a microservicios internos a través de MCP. Podrían consultar datos (solo lectura) o realizar operaciones rutinarias instruyendo a la IA en lenguaje natural. Por ejemplo, “IA, obtén los últimos logs de errores del servicio de monitoreo” – la IA llama a la API interna apropiada y devuelve los resultados. Esto puede impulsar la productividad al descargar consultas simples a la IA.
Automatización Multi-sistema: Imagina una IA orquestando tareas que involucran múltiples sistemas – p. ej., un flujo de trabajo de IA que toma un ticket de soporte, busca información del usuario de un servicio y información del producto de otro, luego crea una entrada en una base de datos. Si cada uno de esos servicios tiene una interfaz MCP, la IA puede saltar sin problemas entre ellos usando llamadas estandarizadas, sin código de integración personalizado para cada sistema. MCP proporciona el pegamento para la automatización inter-sistemas por IA.
API de Lenguaje Natural para Usuarios Finales: Incluso podrías exponer ciertas herramientas a los usuarios finales a través de un chatbot de IA. Por ejemplo, un sitio minorista podría tener un chatbot donde el usuario pregunta “¿Dónde está mi pedido con ID 12345?” El agente de IA backend usa MCP para llamar a la API de seguimiento de pedidos (get_order_status) y luego responde al usuario con la información. FastAPI-MCP en este caso está permitiendo que la IA use la misma API que la aplicación móvil o el sitio web podrían usar, pero a través de la interacción en lenguaje natural.
Prototipo de Plugin de IA: Si estabas considerando construir un Plugin de OpenAI para tu API, implementar FastAPI-MCP logra un objetivo similar pero con un estándar abierto que puede funcionar con múltiples proveedores de IA. Por ejemplo, Anthropic, OpenAI y otros se están alineando en MCP. Obtienes el beneficio de una única implementación que funciona en muchos clientes de IA.

Estas son solo algunas ideas. La conclusión principal es que FastAPI-MCP permite que tu API se conecte fácilmente a flujos de trabajo de IA con un esfuerzo mínimo. Tú te enfocas en escribir la lógica de la API; FastAPI-MCP la hace consumible por IA.

Resumen de Mejores Prácticas

Para asegurar el éxito al usar FastAPI-MCP, ten en cuenta las siguientes mejores prácticas (algunas las hemos mencionado antes):

Da nombres claros a las herramientas: Siempre establece operation_id con un nombre descriptivo para cada endpoint. Esto ayuda a la IA (y a los humanos) a entender qué hace la herramienta (p. ej., update_user_password vs. un nombre predeterminado vago). Usa lower_case o lowerCamelCase por convención, y haz coincidir los nombres con las acciones.
Documenta bien tus endpoints: Cuanto más detalle haya en tu documentación de FastAPI (descripciones, ejemplos, docstrings del modelo de respuesta), más contexto tendrá la IA. Incluye valores de ejemplo para los parámetros si es posible. FastAPI-MCP trasladará estas descripciones a la información de la herramienta MCP.
Valida y sanitiza a fondo: Espera que la IA a veces llame a tus herramientas con parámetros incorrectos o de formas no intencionadas. Asegúrate de que tus validadores de FastAPI (modelos Pydantic, verificaciones de tipo) estén en su lugar para atrapar estos y devolver errores apropiados. También asegúrate de que las respuestas no filtren datos accidentalmente – p. ej., si tu modelo incluye un campo que debería ocultarse, usa response_model_exclude o similar.
Comienza restrictivo, luego abre con cuidado: Especialmente al principio, podría ser prudente exponer un conjunto limitado de endpoints a la IA hasta que veas cómo los usa. Puedes incluir solo unas pocas operaciones seguras de solo lectura y probar las aguas. Con el tiempo, si es necesario, puedes exponer más. Esto limita el riesgo.
Monitorea el uso de IA: Habilita el registro para las llamadas MCP. Podrías agregar middleware o simplemente observar los logs del servidor (que mostrarán las solicitudes a /mcp y posiblemente los endpoints subyacentes). Al monitorear, puedes identificar si la IA está teniendo dificultades (p. ej., llamando a un endpoint repetidamente sin éxito) y luego mejorar tus instrucciones o el diseño del endpoint. También ayuda a detectar el mal uso.
Mantente actualizado con los cambios de la especificación MCP: MCP está evolucionando (el enlace de la especificación proporcionado muestra una versión de fecha). FastAPI-MCP probablemente se actualizará para cumplir con las nuevas versiones. Mantén un ojo en el GitHub de FastAPI-MCP para lanzamientos, y actualiza tu paquete periódicamente para obtener mejoras y correcciones de errores.

Siguiendo estas prácticas, aseguras que la integración de IA no comprometa la integridad o seguridad de tu API, y que la IA pueda aprovechar al máximo la funcionalidad de tu API.

Conclusión

FastAPI-MCP proporciona una forma potente pero fácil de convertir cualquier aplicación FastAPI en un servicio listo para IA. En este tutorial, comenzamos desde conceptos básicos y avanzamos hasta temas avanzados. Recapitulemos rápidamente el viaje:

Aprendimos qué es MCP – un protocolo estándar para la comunicación entre IA y herramientas, comparado con dar a la IA un conector universal para usar APIs externas. FastAPI-MCP implementa esto para FastAPI, requiriendo solo unas pocas líneas de código para configurar.
Recorrimos un inicio rápido – instalando el paquete, montándolo en una aplicación FastAPI y verificando que el endpoint MCP esté activo. Con un código mínimo, nuestros endpoints API se convirtieron en herramientas MCP descubribles.
Discutimos la estructura del proyecto – cómo integrar en una sola aplicación o dividir en servicios API y MCP para mayor flexibilidad. Planificar tu despliegue temprano ayuda a evitar refactorizaciones posteriores.
Exploramos la personalización – nombrando herramientas a través de operation_id, agregando información detallada del esquema y filtrando qué endpoints se exponen para mantener el control.
Abordamos la seguridad a través de la inyección de dependencias – usando Depends() para requerir tokens de autenticación o claves API para llamadas MCP, e incluso habilitando flujos OAuth para escenarios avanzados. Enfatizamos el uso de las utilidades de seguridad existentes de FastAPI para mantener segura la interfaz MCP.
Integramos con clientes de IA – demostrando cómo un IDE de IA puede conectarse a través de SSE o a través de un proxy mcp-remote. Vimos que una IA puede entonces llamar a funciones API en lenguaje natural, convirtiendo efectivamente tu aplicación en parte de la caja de herramientas de la IA.
Cubrimos el despliegue – destacando que despliegas aplicaciones FastAPI-MCP de manera muy similar a cualquier aplicación FastAPI, prestando atención a SSE y posiblemente al escalado separado. La contenerización y el despliegue en la nube funcionan sin problemas, permitiendo el uso en el mundo real de tu servicio MCP.
Repasamos las pruebas y la solución de problemas – usando herramientas como MCP Inspector para validar tu configuración, y señalando errores comunes (como olvidar actualizar la lista de herramientas o desajustes de autenticación).
Vimos casos de uso del mundo real – desde asistentes de documentación hasta automatización multi-sistema, ilustrando la versatilidad de exponer una API a la IA.
Finalmente, resumimos las mejores prácticas para asegurar una operación fluida y segura cuando humanos e IA comiencen a consumir tu API en tándem.

Siguiendo esta guía, deberías estar bien equipado para implementar FastAPI-MCP en tus proyectos. Puedes crear aplicaciones ricas e integradas con IA que aprovechen el poder de los grandes modelos de lenguaje para interactuar con tus servicios FastAPI de maneras inteligentes. A medida que crece el ecosistema MCP (con más clientes y servidores emergiendo), ya estás a la vanguardia con una API que habla el lenguaje de la IA.

Próximos Pasos: Experimenta con tu propia configuración API + MCP. Intenta conectar diferentes clientes de IA (Cursor, VSCode, etc.) y ve cómo la IA usa tus herramientas. Únete a la comunidad FastAPI-MCP (el Slack “MCParty”) si tienes preguntas o ideas – siendo un proyecto de código abierto, las contribuciones y comentarios son bienvenidos. ¡Feliz codificación, y bienvenido a la próxima generación de aplicaciones impulsadas por IA!

Referencias

Consejo: El repositorio fastapi-mcp y la especificación MCP están evolucionando rápidamente—revisa esas fuentes a menudo para mantenerte actualizado.

¿Disfrutaste esta publicación? ¿La encontraste perspicaz? Siéntete libre de dejar un comentario abajo para compartir tus pensamientos o hacer preguntas. Se requiere una cuenta de GitHub para unirse a la discusión.