FastMCP MCP — Casos de uso, Instalar & Demo en vivo

Por qué usarlo

Características clave

Un único decorador por herramienta: @mcp.tool o @mcp.resource
Los type hints se convierten en esquemas JSON — sin escribir esquemas manualmente
Async-first, soporta sincrónico también — typing estándar funciona
Transports incluidos: stdio (para clientes de escritorio), SSE / HTTP transmisible (para remoto)

Demo en vivo

Cómo se ve en la práctica

fastmcp.replay ▶ listo

0/0

Instalar

Elige tu cliente

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "fastmcp": {
      "command": "uvx",
      "args": [
        "fastmcp"
      ]
    }
  }
}

Abre Claude Desktop → Settings → Developer → Edit Config. Reinicia después de guardar.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "fastmcp": {
      "command": "uvx",
      "args": [
        "fastmcp"
      ]
    }
  }
}

Cursor usa el mismo esquema mcpServers que Claude Desktop. La configuración del proyecto prevalece sobre la global.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "fastmcp": {
      "command": "uvx",
      "args": [
        "fastmcp"
      ]
    }
  }
}

Haz clic en el icono MCP Servers de la barra lateral de Cline y luego en "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "fastmcp": {
      "command": "uvx",
      "args": [
        "fastmcp"
      ]
    }
  }
}

Mismo formato que Claude Desktop. Reinicia Windsurf para aplicar.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "fastmcp",
      "command": "uvx",
      "args": [
        "fastmcp"
      ]
    }
  ]
}

Continue usa un array de objetos de servidor en lugar de un mapa.

~/.config/zed/settings.json

{
  "context_servers": {
    "fastmcp": {
      "command": {
        "path": "uvx",
        "args": [
          "fastmcp"
        ]
      }
    }
  }
}

Añádelo a context_servers. Zed recarga en caliente al guardar.

claude mcp add fastmcp -- uvx fastmcp

Un solo comando. Verifica con claude mcp list. Quita con claude mcp remove.

Casos de uso

Usos del mundo real: FastMCP

Expone una API REST interna como un MCP en menos de una hora

👤 Ingenieros backend con un servicio Python existente ⏱ ~45 min intermediate

Cuándo usarlo: Tienes una API de la empresa que los agentes deberían poder llamar, y no quieres escribir una especificación de cliente desde cero.

Requisitos previos

Python 3.10+ — python --version
uv instalado — curl -LsSf https://astral.sh/uv/install.sh | sh

Flujo

Inicializa el proyecto

Genera un proyecto de servidor FastMCP llamado 'acme-api-mcp' con una herramienta inicial. Usa uv para gestión de dependencias.✓ Copiado

→ pyproject.toml + server.py con un ejemplo de @mcp.tool funcional
Envuelve los 3 endpoints de mayor valor

Mi API interna tiene endpoints /orders/{id}, /customers/search, /invoices/{id}/pdf. Escribe una herramienta FastMCP para cada uno, usando httpx.AsyncClient y leyendo AUTH_TOKEN del entorno.✓ Copiado

→ 3 funciones decoradas con type hints + docstrings que se conviertan en descripciones de herramientas
Prueba localmente con el MCP Inspector

Ejecuta el servidor con uv run mcp dev server.py. Abre el inspector y llama a cada herramienta con una entrada realista.✓ Copiado

→ Las herramientas devuelven JSON esperado, sin trazas de pila

Resultado: Un servidor MCP funcional que puedas apuntar a Claude Desktop o a cualquier cliente MCP.

Errores comunes

Los secretos se filtran en las descripciones de herramientas porque los imprimiste en docstrings — Usa docstrings para describir el comportamiento, no ejemplos con tokens reales. Carga secretos a través de os.environ y nunca los repitas en errores
Async + sync mezclados, causa errores de bucle de eventos — Elige uno — si tu cliente HTTP es async, haz toda la herramienta async; no llames asyncio.run dentro de una herramienta

Expone documentos de la empresa como recursos MCP para RAG

👤 Ingenieros de plataforma construyendo infraestructura de agentes ⏱ ~30 min intermediate

Cuándo usarlo: Quieres que el agente auto-descubra y extraiga conocimiento de la empresa sin llamadas a herramientas para cada archivo.

Flujo

Define un listado de recursos

Define un recurso FastMCP en URI docs://{path} que liste todos los archivos markdown bajo ./docs/ y devuelva su contenido al leer.✓ Copiado

→ Recurso registrado, el inspector muestra la lista
Agrega un recurso plantilla

Agrega una plantilla de recurso docs://{category}/{slug} que devuelva el archivo coincidente. Documenta los valores válidos de {category}.✓ Copiado

→ Plantilla registrada, las búsquedas parametrizadas funcionan
Prueba en un cliente real

Conecta Claude Desktop al servidor. Verifica que el menú Recursos liste todos los documentos y se cargue el contenido.✓ Copiado

→ Los recursos aparecen como contexto adjuntable

Resultado: Una superficie de conocimiento respaldada por recursos que el agente puede extraer de forma nativa — más limpio que llamadas a herramientas para contenido estático.

Errores comunes

Los listados grandes de recursos abruman la UI del cliente — Pagina o filtra en tu endpoint de lista; no es necesario que todos los archivos estén expuestos

Despliega un servidor FastMCP como un endpoint SSE remoto

👤 Ingenieros de plataforma sirviendo a múltiples equipos ⏱ ~60 min advanced

Cuándo usarlo: Múltiples desarrolladores necesitan el mismo MCP — alójalo una vez, no hagas que todos ejecuten stdio localmente.

Requisitos previos

Un host de contenedores (Cloud Run, Fly, Railway) — Funciona cualquier runtime compatible con Docker

Flujo

Cambia el transport a SSE

Modifica server.py para ejecutar mcp.run(transport='sse', host='0.0.0.0', port=8080). Agrega un Dockerfile mínimo.✓ Copiado

→ El curl localhost:8080/sse local muestra el handshake SSE
Despliega detrás de autenticación

Despliega a Cloud Run con autenticación IAM. Coloca el endpoint /sse con una verificación de autenticación basada en encabezados en un middleware FastAPI.✓ Copiado

→ URL pública con 401 en solicitudes no autenticadas
Conecta clientes

Comparte el comando de conexión con los compañeros de equipo: npx -y mcp-remote https://mcp.acme.com/sse. Verifica que su Claude Desktop recoja las herramientas.✓ Copiado

→ Los clientes de los miembros del equipo ven las mismas herramientas

Resultado: Un MCP remoto compartido — un único código base, muchos usuarios, fácil de actualizar.

Errores comunes

Las conexiones SSE se caen detrás de algunos proxies corporativos — Usa transporte HTTP transmisible en su lugar (especificación más nueva) o documenta un requisito de VPN/ruta directa

Combinar con: cloud-run

Combinaciones

Combínalo con otros MCPs para multiplicar por 10

fastmcp + cloud-run

Construye una vez, despliega a Cloud Run, comparte con el equipo

Envuelve mi API de precios interna como un servidor FastMCP, containeriza y despliega a Cloud Run con autenticación IAM.✓ Copiado

fastmcp + fastapi-mcp

Compara enfoques — FastMCP para greenfield, fastapi-mcp para apps FastAPI existentes

Tengo un servicio FastAPI existente. ¿Debo agregar fastapi-mcp para exponerlo o reescribir en FastMCP? Compara basándote en mis rutas.✓ Copiado

Herramientas

Lo que expone este MCP

Herramienta	Entradas	Cuándo llamar	Coste
@mcp.tool	función decorada con firma tipada	Envuelve cualquier función que quieras que los agentes llamen	gratuito
@mcp.resource	plantilla URI + función	Expone contenido legible (documentos, configuración, snapshots de datos)	gratuito
@mcp.prompt	función decorada que devuelve Message[]	Proporciona andamios de prompt multi-turno reutilizables a los clientes	gratuito
mcp.run	transport: 'stdio'\|'sse'\|'streamable-http', host?, port?	Punto de entrada — llama al final de tu script principal	gratuito
Context (ctx) parameter	inyecta ctx: Context en cualquier herramienta	Herramientas de larga duración que necesitan transmitir progreso o registrar	gratuito

Coste y límites

Lo que cuesta ejecutarlo

Cuota de API: Ninguno — esto es un framework, no un servicio
Tokens por llamada: Tu servidor ejecuta cualquier llamada LLM; el overhead del framework es negligible
Monetario: Gratuito, código abierto
Consejo: Usa recursos en lugar de herramientas para contenido estático — los recursos son más económicos en tokens porque se pre-declaran

Seguridad

Permisos, secretos, alcance

Almacenamiento de credenciales: Tu elección — variables de entorno son idiomáticas; carga secretos al inicio del proceso, no por llamada

Salida de datos: Dondequiera que tus funciones de herramienta se comuniquen

Resolución de problemas

Errores comunes y soluciones

Esquema de herramienta sin campos requeridos en el cliente

Los parámetros de tu función necesitan type hints. Un simple def foo(x) genera un esquema inútil — usa def foo(x: str) con un docstring.

Verificar: Ejecuta `uv run mcp dev server.py` y verifica el esquema de herramientas del Inspector

El servidor inicia pero el cliente ve 0 herramientas

Estás mezclando stdio con configuración incorrecta de SSE. Para Claude Desktop usa transport='stdio'; para mcp-remote usa 'sse'.

`ImportError: No module named 'fastmcp'`

Instala con uv pip install fastmcp o agrega a las dependencias de pyproject.toml. Verifica que estés ejecutando el servidor desde el mismo venv.

Verificar: uv pip show fastmcp

La herramienta async se cuelga en la primera llamada

Importaste httpx sincrónico dentro de una herramienta async. Usa httpx.AsyncClient con async with — nunca mezcles.

Alternativas

FastMCP vs otros

Alternativa	Cuándo usarla	Contrapartida
TypeScript MCP SDK	Eres una tienda TS/Node y quieres quedarte allí	Oficial, bien mantenido, DX similar — solo diferente lenguaje
fastapi-mcp	Ya tienes una app FastAPI y quieres exponer rutas como herramientas	Menos control sobre la superficie de MCP pero refactorización cero para servicios existentes
csharp-sdk	Tienda .NET	De primera parte, pero ecosistema más pequeño de ejemplos

Más

Recursos

📖 Lee el README oficial en GitHub

🐙 Ver issues abiertas

🔍 Ver todos los 400+ servidores MCP y Skills