Cómo usar el servidor MCP de FastAPI

FastAPI MCP Server es una herramienta revolucionaria que tiende un puente entre tus aplicaciones FastAPI y los agentes de IA utilizando el Protocolo de Contexto de Modelo (MCP). En una era donde la integración de la IA es cada vez más importante, esta solución de configuración cero te permite exponer tus endpoints FastAPI existentes como herramientas que pueden ser descubiertas y utilizadas por modelos y agentes de IA con un mínimo esfuerzo.

💡

Antes de comenzar a configurar el Kubernetes MCP Server, considera explorar Apidog: una herramienta poderosa para diseñar, probar y documentar APIs. Apidog simplifica la integración de APIs con modelos estructurados y una colaboración fluida. Cuando se combina con Zapier MCP, mejora la automatización y la gestión de APIs.

button

Introducción a FastAPI MCP

El Protocolo de Contexto de Modelo (MCP) es un estándar emergente que permite a los modelos de IA interactuar con herramientas y recursos externos. FastAPI MCP Server sirve como puente entre tus aplicaciones FastAPI existentes y los agentes de IA compatibles con MCP como Claude de Anthropic, Cursor IDE y otros, sin necesidad de reescribir tu API ni de aprender nuevos frameworks complejos.

Lo que hace que FastAPI MCP sea realmente notable es su enfoque de configuración cero. Convierte automáticamente tus endpoints FastAPI existentes en herramientas compatibles con MCP, preservando los esquemas de tus endpoints, la documentación y la funcionalidad. Esto significa que los agentes de IA pueden descubrir e interactuar con tus APIs con una configuración mínima requerida por tu parte.

Puedes encontrar el repositorio del servidor FastAPI MCP en: https://github.com/tadata-org/fastapi_mcp

Empezando con FastAPI MCP

Instalación

Antes de que puedas usar FastAPI MCP, necesitarás instalarlo. Los desarrolladores recomiendan usar uv, un instalador de paquetes de Python rápido, pero también puedes usar el método tradicional pip:

Usando uv:

uv add fastapi-mcp

Usando pip:

pip install fastapi-mcp

Implementación Básica

Integrar FastAPI MCP con tu aplicación FastAPI existente no podría ser más sencillo. Aquí está la implementación más básica:

from fastapi import FastAPI
from fastapi_mcp import FastApiMCP

# Your existing FastAPI application
app = FastAPI()

# Create the MCP server
mcp = FastApiMCP(
    app,
    name="My API MCP",
    description="My API description",
    base_url="http://localhost:8000"  # Important for routing requests
)

# Mount the MCP server to your FastAPI app
mcp.mount()

¡Eso es todo! Con este simple código, tu servidor MCP ahora está disponible en https://app.base.url/mcp. Cuando un cliente compatible con MCP se conecta a este endpoint, descubrirá automáticamente todas tus rutas FastAPI como herramientas disponibles.

Entendiendo los Nombres de las Herramientas MCP y los IDs de Operación

Cuando FastAPI MCP expone tus endpoints como herramientas, utiliza el operation_id de tus rutas FastAPI como los nombres de las herramientas MCP. FastAPI genera automáticamente estos IDs cuando no se proporcionan explícitamente, pero pueden ser crípticos y menos fáciles de usar.

Compara estos dos enfoques:

# Auto-generated operation_id (less user-friendly)
@app.get("/users/{user_id}")
async def read_user(user_id: int):
    return {"user_id": user_id}

# Explicit operation_id (more user-friendly)
@app.get("/users/{user_id}", operation_id="get_user_info")
async def read_user(user_id: int):
    return {"user_id": user_id}

En el primer ejemplo, la herramienta podría llamarse algo así como "read_user_users__user_id__get", mientras que el segundo ejemplo simplemente sería "get_user_info". Para una mejor usabilidad, especialmente cuando los agentes de IA interactúan con tus herramientas, se recomienda definir explícitamente los IDs de operación que sean claros y descriptivos.

Opciones de Configuración Avanzadas

FastAPI MCP proporciona varias opciones de personalización para adaptar cómo se expone tu API a los clientes MCP.

Personalizando la Descripción del Esquema

Puedes controlar cuánta información se incluye en las descripciones de las herramientas:

mcp = FastApiMCP(
    app,
    name="My API MCP",
    base_url="http://localhost:8000",
    describe_all_responses=True,  # Include all possible response schemas
    describe_full_response_schema=True  # Include full JSON schema details
)

Filtrando Endpoints

Es posible que desees controlar qué endpoints se exponen como herramientas MCP. FastAPI MCP ofrece varios mecanismos de filtrado:

# Only include specific operations by operation ID
mcp = FastApiMCP(
    app,
    include_operations=["get_user", "create_user"]
)

# Exclude specific operations
mcp = FastApiMCP(
    app,
    exclude_operations=["delete_user"]
)

# Filter by tags
mcp = FastApiMCP(
    app,
    include_tags=["users", "public"]
)

# Exclude by tags
mcp = FastApiMCP(
    app,
    exclude_tags=["admin", "internal"]
)

# Combine filtering strategies
mcp = FastApiMCP(
    app,
    include_operations=["user_login"],
    include_tags=["public"]
)

Ten en cuenta que no puedes combinar filtros de inclusión y exclusión del mismo tipo (operaciones o etiquetas), pero puedes usar filtros de operación junto con filtros de etiquetas.

Estrategias de Despliegue

FastAPI MCP ofrece flexibilidad en cómo implementas tu servidor MCP.

Montando en la Aplicación Original

El enfoque más simple es montar el servidor MCP directamente en tu aplicación FastAPI original como se muestra en el ejemplo básico. Esto crea un endpoint en /mcp en tu aplicación existente.

Desplegando como un Servicio Separado

También puedes crear un servidor MCP desde una aplicación FastAPI y montarlo en una aplicación diferente, lo que te permite desplegar tu API y su interfaz MCP por separado:

from fastapi import FastAPI
from fastapi_mcp import FastApiMCP

# Your original API app
api_app = FastAPI()
# Define your endpoints here...

# A separate app for the MCP server
mcp_app = FastAPI()

# Create MCP server from the API app
mcp = FastApiMCP(
    api_app,
    base_url="http://api-host:8001"  # URL where the API app will be running
)

# Mount the MCP server to the separate app
mcp.mount(mcp_app)

# Now run both apps separately:
# uvicorn main:api_app --host api-host --port 8001
# uvicorn main:mcp_app --host mcp-host --port 8000

Esta separación puede ser beneficiosa para la gestión de recursos, la seguridad y el escalado.

Actualizando MCP Después de Añadir Nuevos Endpoints

Si añades endpoints a tu aplicación FastAPI después de crear el servidor MCP, necesitarás actualizar el servidor para incluirlos:

# Initial setup
app = FastAPI()
mcp = FastApiMCP(app)
mcp.mount()

# Later, add a new endpoint
@app.get("/new/endpoint/", operation_id="new_endpoint")
async def new_endpoint():
    return {"message": "Hello, world!"}

# Refresh the MCP server to include the new endpoint
mcp.setup_server()

Conectando a tu Servidor MCP

Una vez que tu aplicación FastAPI con integración MCP se está ejecutando, los clientes pueden conectarse a ella de varias maneras.

Usando Eventos Enviados por el Servidor (SSE)

Muchos clientes MCP, como Cursor IDE, admiten conexiones SSE:

Ejecuta tu aplicación
En Cursor → Settings → MCP, usa la URL de tu endpoint del servidor MCP (por ejemplo, http://localhost:8000/mcp) como la URL SSE
Cursor descubrirá automáticamente todas las herramientas y recursos disponibles

Usando MCP Proxy para Clientes Sin Soporte SSE

Para clientes que no admiten SSE directamente (como Claude Desktop):

Ejecuta tu aplicación
Instala la herramienta MCP proxy: uv tool install mcp-proxy
Configura tu cliente para usar mcp-proxy

Para Claude Desktop en Windows, crea un archivo de configuración (claude_desktop_config.json):

{
  "mcpServers": {
    "my-api-mcp-proxy": {
      "command": "mcp-proxy",
      "args": ["http://127.0.0.1:8000/mcp"]
    }
  }
}

Para macOS, necesitarás especificar la ruta completa al ejecutable mcp-proxy, que puedes encontrar usando which mcp-proxy.

Casos de Uso en el Mundo Real

FastAPI MCP abre numerosas posibilidades para aplicaciones impulsadas por IA:

Herramientas de Análisis de Datos: Expón endpoints de procesamiento de datos que los agentes de IA puedan usar para analizar los datos del usuario sin requerir integraciones personalizadas para cada modelo de IA.
Sistemas de Gestión de Contenido: Permite que las herramientas de IA obtengan y actualicen contenido a través de tu API CMS existente, haciendo que la creación y gestión de contenido sean más eficientes.
Motores de Búsqueda Personalizados: Permite a los asistentes de IA buscar en tus bases de datos especializadas o repositorios de contenido a través de una interfaz API simple.
Operaciones de Comercio Electrónico: Permite que los agentes de IA verifiquen el inventario, la información del producto o realicen pedidos a través de tus endpoints API de comercio electrónico existentes.
Procesamiento de Documentos: Proporciona a las herramientas de IA la capacidad de crear, convertir o analizar documentos utilizando tus capacidades de procesamiento de documentos backend.

Mejores Prácticas

Para aprovechar al máximo FastAPI MCP, considera estas mejores prácticas:

Usa IDs de operación explícitos: Define IDs de operación claros y descriptivos para todos tus endpoints para que sean más utilizables por los agentes de IA.
Proporciona documentación completa: Incluye descripciones detalladas para cada endpoint y parámetro para ayudar a los modelos de IA a comprender cómo usar tus herramientas de manera efectiva.
Usa nombres de parámetros consistentes: Adopta convenciones de nomenclatura consistentes para parámetros similares en diferentes endpoints.
Considera las implicaciones de seguridad: Ten en cuenta qué endpoints expones a través de MCP e implementa la autenticación adecuada donde sea necesario.
Supervisa el uso: Realiza un seguimiento de cómo los agentes de IA están utilizando tus herramientas MCP para identificar patrones, errores o áreas de mejora.

Conclusión

FastAPI MCP Server representa un importante paso adelante para hacer que los servicios backend sean accesibles para los agentes de IA. Al convertir automáticamente tus endpoints FastAPI existentes en herramientas compatibles con MCP con configuración cero, elimina la necesidad de integraciones personalizadas o ajustes complejos en el diseño de tu API.

A medida que el ecosistema MCP continúa creciendo y más modelos de IA adoptan este estándar, tener tus APIs expuestas a través de FastAPI MCP posicionará tus servicios para que sean fácilmente accesibles a una amplia gama de agentes y herramientas de IA. Ya sea que estés construyendo herramientas internas, servicios para desarrolladores o APIs públicas, FastAPI MCP ofrece un camino sencillo para hacer que tus servicios sean accesibles para la IA.

Siguiendo la guía de este artículo, puedes integrar rápidamente FastAPI MCP en tus aplicaciones FastAPI existentes y comenzar a explorar las posibilidades de la automatización impulsada por IA y la interacción con tus servicios.