Herramientas, recursos y prompts en MCP
En esta página
Actualizado el 2 de noviembre de 2026 — MCP Python SDK v2. Este curso sigue ahora la versión 2 del SDK
mcp(2.3.0 a fecha de 2 de octubre de 2026):MCPServersustituye aFastMCP, la configuración del transporte se traslada arun()ostreamable_http_app(), y una aplicación expuesta bajo un nombre de host real debe declarar dicho nombre de host (transport_security). Esta es también la versión exigida por el SDK de Mistral: el extramistralai[agents]requieremcp>=2.2.0,<3.0. Fuentes: Novedades en la v2 · Guía de migración · Despliegue y escalado.
Tres capacidades, tres intenciones
Un servidor MCP puede exponer tres tipos de capacidades a sus clientes. No son intercambiables: cada una responde a una necesidad distinta, y confundirlas da lugar a servidores difíciles de utilizar para el modelo. Esta lección las examina una por una, antes de abordar la pregunta que determina la calidad del servidor: ¿cuántas herramientas y con qué granularidad?
Herramientas: funciones ejecutables
Las herramientas son la capacidad más utilizada del protocolo. Una herramienta es una función que el modelo puede decidir invocar para realizar una acción o recuperar información. Su definición se basa en cuatro elementos: un nombre único y descriptivo (create_issue, get_weather), una descripción en texto que indica al modelo cuándo debe llamarla, un esquema JSON para los parámetros de entrada con sus tipos y restricciones, y un formato de retorno, habitualmente texto o JSON.
from mcp.server.mcpserver import MCPServer
app = MCPServer("My Server")
@app.tool()
def get_weather(latitude: float, longitude: float) -> str:
"""Recupera el tiempo actual para las coordenadas indicadas.
Args:
latitude: Latitud en grados decimales (-90 a 90)
longitude: Longitud en grados decimales (-180 a 180)
Returns:
Descripción textual del tiempo actual
"""
# Lógica de llamada a la API del tiempo
return f"Soleado, 22 °C en ({latitude}, {longitude})"
No subestimes la descripción ni la tipificación: el modelo no ve nada más. No tiene acceso a tu código, no puede adivinar tus intenciones ni puede probar una llamada para ver qué ocurre. Las descripciones vagas o los parámetros mal tipificados producen mecánicamente llamadas incorrectas.
Unos pocos hábitos hacen que tus herramientas sean significativamente más fiables. Nómbralas según lo que hacen: book_restaurant lo dice todo, process_request no dice nada; y describe tanto la acción como el contenido devuelto, ya que el modelo debe anticipar qué va a recuperar. Anota siempre los parámetros en Python y escribe docstrings estructurados con Args y Returns: estos alimentan el esquema que ve el modelo. Por último, devuelve valores legibles en lugar de identificadores opacos; una herramienta que devuelve "John Smith" permite al modelo componer una frase, mientras que una que devuelve un UUID le obliga a adivinar.
Recursos: datos legibles
Los recursos exponen datos que el cliente puede leer sin efectos secundarios. El matiz con las herramientas se resume en un verbo: una herramienta hace algo, un recurso contiene algo. El contenido de un archivo de configuración, una base de conocimientos, documentación de API o el estado actual de un sistema son todos recursos naturales.
@app.resource("config://database")
def get_db_config() -> str:
"""Configuración actual de la base de datos."""
return json.dumps({
"host": "localhost",
"port": 5432,
"database": "production"
})
Cada recurso se identifica mediante un URI —config://database, file:///path/to/doc— que el cliente puede listar y luego leer bajo demanda. En la práctica, se usan menos que las herramientas, ya que una simple herramienta que devuelve datos cubre la mayoría de las necesidades. Siguen siendo útiles cuando quieres publicar datos estáticos o semiestáticos sin lógica de ejecución detrás.
Prompts: plantillas reutilizables
Los prompts de MCP son plantillas parametrizables que el servidor pone a disposición. Sirven para compartir instrucciones probadas para una tarea determinada, en lugar de dejar que cada uno reinvente su redacción.
@app.prompt()
def code_review(language: str, code: str) -> str:
"""Genera un prompt de revisión de código para el lenguaje indicado."""
return f"""Eres un experto en {language}.
Analiza el siguiente código e identifica:
1. Errores potenciales
2. Problemas de rendimiento
3. Mejoras de legibilidad
Código a analizar:
```{language}
{code}
```"""
Este uso tiene más sentido en un entorno de equipo. Un desarrollador senior codifica sus prompts de revisión de código, depuración o análisis de arquitectura en un servidor MCP, y todo el equipo accede a ellos desde su propio cliente con la misma calidad de instrucción.
Negociación de capacidades
Cuando un cliente se conecta a un servidor, una fase de negociación precede a cualquier uso:
- El cliente solicita las capacidades del servidor
- El servidor responde con su lista de herramientas, recursos y prompts
- El cliente presenta estas capacidades al modelo de lenguaje
- El modelo utiliza las descripciones para decidir qué invocar
Esta negociación es dinámica, y esa es una propiedad aprovechable: el mismo servidor puede anunciar diferentes capacidades dependiendo del usuario conectado o del contexto de la llamada; una cuenta de administrador verá herramientas que una cuenta de solo lectura nunca verá.
¿Cuántas herramientas por servidor?
La pregunta parece trivial, pero condiciona la tasa de error de tu agente. Mantén tus servidores enfocados: de tres a diez herramientas bien definidas funcionan mejor que cincuenta genéricas. Más allá de cierto volumen, el modelo dispersa sus elecciones y acaba llamando a la herramienta equivocada o apilando llamadas innecesarias.
Si tu ámbito funcional es amplio, divídelo en varios servidores especializados: uno para operaciones de Git, otro para gestión de proyectos, otro para monitorización. El cliente sabe cómo conectarse a varios servidores simultáneamente y activar solo los requeridos por la tarea actual, lo que equivale a cargar el contexto útil en lugar de todo el catálogo.
Un último equilibrio merece tu atención: la granularidad. Exponer tres herramientas para listar restaurantes, comprobar disponibilidad y luego reservar obliga al modelo a orquestar una secuencia, con riesgo de error en cada paso. Una única herramienta de flujo de trabajo —book_restaurant— encapsula la secuencia completa, reduce el número de idas y vueltas y traslada la lógica de negocio allí donde es comprobable: en tu código.
Puntos clave
- Herramientas = acciones ejecutables (90 % de los casos de uso), requieren descripción y tipificación precisas
- Recursos = datos legibles vía URI, sin efectos secundarios
- Prompts = plantillas reutilizables, útiles para equipos
- Mantén tus servidores enfocados (máximo 3–10 herramientas)
- Prefiere herramientas de flujo de trabajo frente a herramientas excesivamente granulares
- La calidad de la descripción determina la eficiencia del modelo