Implementación de herramientas: esquema JSON y controladores
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 requerida por el Mistral SDK: el extramistralai[agents]necesitamcp>=2.2.0,<3.0. Fuentes: Novedades en la v2 · Guía de migración · Despliegue y escalado.
La anatomía de una herramienta MCP
Una herramienta MCP parece una función de Python, pero desde la perspectiva del modelo no lo es. Se trata de un contrato de cuatro partes: un nombre, una descripción, un esquema de entrada JSON y un controlador que ejecuta la lógica. El modelo nunca ve tu código; solo ve este contrato. Una herramienta perfectamente implementada pero mal descrita nunca se invocará, o se llamará en el momento equivocado. Por tanto, la calidad del contrato determina la eficacia del servidor mucho más que la calidad de la implementación.
Lo que el decorador construye por ti
MCPServer genera este contrato automáticamente a partir de la firma de tu función y su docstring. Escribes Python estándar:
from mcp.server.mcpserver import MCPServer
app = MCPServer("Mi servidor")
@app.tool()
def search_documents(
query: str,
max_results: int = 10,
language: str = "fr",
include_archived: bool = False,
) -> str:
"""Busca documentos en la base de conocimientos.
Args:
query: Términos de búsqueda (2-500 caracteres)
max_results: Número máximo de resultados (1-100, predeterminado: 10)
language: Código de idioma ISO 639-1 (predeterminado: fr)
include_archived: Incluir documentos archivados (predeterminado: false)
Returns:
JSON con la lista de documentos encontrados y el recuento total
"""
# Lógica de búsqueda
...
Y el modelo recibe esto:
{
"name": "search_documents",
"description": "Busca documentos en la base de conocimientos.",
"inputSchema": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Términos de búsqueda (2-500 caracteres)"
},
"max_results": {
"type": "integer",
"description": "Número máximo de resultados (1-100, predeterminado: 10)",
"default": 10
},
"language": {
"type": "string",
"description": "Código de idioma ISO 639-1 (predeterminado: fr)",
"default": "fr"
},
"include_archived": {
"type": "boolean",
"description": "Incluir documentos archivados (predeterminado: false)",
"default": false
}
},
"required": ["query"]
}
}
Compara ambos bloques línea por línea: cada anotación de tipo se convierte en un tipo JSON, cada valor predeterminado se transforma en un campo default, cada línea de la sección Args se convierte en la descripción de un parámetro, y el único argumento sin valor predeterminado acaba en required. En otras palabras, todo lo que omitas en la docstring desaparece por completo del contrato.
Nombrar y, después, describir
El nombre de la herramienta es el nombre de la función, y el modelo lo usa como primera pista. Un verbo de acción seguido de un objeto claro no deja lugar a ambigüedades, mientras que un nombre genérico o técnico obliga al modelo a adivinar:
# Correcto: verbo de acción + objeto claro
@app.tool()
def create_issue(title: str, body: str) -> str: ...
@app.tool()
def search_repositories(query: str) -> str: ...
@app.tool()
def get_user_profile(username: str) -> str: ...
# Incorrecto: vago, ambiguo, técnico
@app.tool()
def process(data: str) -> str: ... # Demasiado vago
@app.tool()
def handle_request(req: str) -> str: ... # Incomprensible para el LLM
@app.tool()
def db_query(sql: str) -> str: ... # Demasiado técnico
La docstring toma entonces el relevo y constituye la pieza más crítica de todo tu servidor. Debe responder a tres preguntas en este orden: cuándo usar esta herramienta, qué parámetros proporcionar con su formato y restricciones, y qué esperar como respuesta. El siguiente ejemplo muestra cómo queda esto en un caso real:
@app.tool()
def book_restaurant(
restaurant_name: str,
date: str,
party_size: int,
special_requests: str = "",
) -> str:
"""Reserva una mesa en un restaurante.
Realiza una reserva completa incluyendo confirmación
por correo electrónico. Usa esta herramienta cuando el usuario quiera
reservar un restaurante específico.
Args:
restaurant_name: Nombre exacto del restaurante
date: Fecha y hora en formato ISO 8601 (p. ej., 2026-04-15T19:30:00)
party_size: Número de comensales (1-20)
special_requests: Peticiones especiales (alergias, ocasión, etc.)
Returns:
JSON con el número de reserva, la confirmación
y los detalles del restaurante
"""
...
El párrafo que sigue a la primera línea es lo que más suelen echar en falta los servidores amateur. Sin él, el modelo sabe qué hace la herramienta, pero no en qué situación debe activarla. Y el ejemplo de fecha ISO 8601 te ahorrará decenas de llamadas con "15 de abril a las 19:30".
Tipos, controladores asíncronos y validación
MCPServer traduce las anotaciones comunes de Python a sus equivalentes en esquema JSON.
| Python | Esquema JSON | Ejemplo |
|---|---|---|
str | string | "texto" |
int | integer | 42 |
float | number | 3.14 |
bool | boolean | true |
list[str] | array de string | ["a", "b"] |
dict | object | {"clave": "valor"} |
Optional[str] | string (nullable) | "texto" o null |
En cuanto una herramienta sale de su propio proceso —llamada de red, consulta a base de datos, lectura de archivo remoto—, declárala async. Un controlador síncrono esperando una respuesta HTTP bloquea todo el servidor, y a tus otros usuarios con él:
import httpx
@app.tool()
async def fetch_api_data(endpoint: str) -> str:
"""Recupera datos de una API externa.
Args:
endpoint: Ruta del endpoint de la API (p. ej., /users/123)
Returns:
Datos JSON de la API
"""
async with httpx.AsyncClient() as client:
response = await client.get(f"https://api.example.com{endpoint}")
response.raise_for_status()
return response.text
El esquema JSON restringe tipos, nunca valores: nada impide que el modelo envíe un nombre de 3.000 caracteres o un rol inventado. Por tanto, valida siempre en el punto de entrada del controlador y devuelve un mensaje que indique la corrección necesaria:
import json
@app.tool()
def create_user(name: str, email: str, role: str = "viewer") -> str:
"""Crea un nuevo usuario.
Args:
name: Nombre completo (2-100 caracteres)
email: Dirección de correo electrónico válida
role: Rol: viewer, editor, admin (predeterminado: viewer)
Returns:
JSON con los detalles del usuario creado
"""
# Validación
if len(name) < 2 or len(name) > 100:
return json.dumps({"error": "El nombre debe tener entre 2 y 100 caracteres"})
if "@" not in email or "." not in email:
return json.dumps({"error": "Dirección de correo electrónico no válida"})
valid_roles = ("viewer", "editor", "admin")
if role not in valid_roles:
return json.dumps({"error": f"Rol no válido. Opciones: {', '.join(valid_roles)}"})
# Creación...
return json.dumps({"success": True, "user": {"name": name, "email": email, "role": role}})
El tercer mensaje enumera los valores permitidos. El modelo puede entonces autocorregirse y volver a llamar a la herramienta, en lugar de rendirse ante un error “Rol no válido” sin explicación.
Perfeccionar el valor de retorno
Una herramienta MCP devuelve siempre texto, pero ese texto puede ser JSON estructurado, que el modelo interpreta muy bien. El contraste entre estas dos devoluciones resume lo esencial:
# Correcto: JSON estructurado y legible
return json.dumps({
"success": True,
"user": {
"name": "Alice Dupont",
"email": "[email protected]",
"role": "editor",
},
"message": "Usuario creado correctamente"
}, ensure_ascii=False)
# Incorrecto: datos crudos difíciles de usar
return "OK:user_id=abc123:status=created"
Prefiere siempre valores legibles por un humano frente a identificadores internos: el modelo puede usar inmediatamente "Alice Dupont" en su respuesta, mientras que un UUID obliga a una llamada adicional para averiguar de quién se habla. Por el contrario, cuidado con las devoluciones hinchadas: cincuenta campos por registro llenan la ventana de contexto sin aportar valor. El reflejo correcto al escribir una herramienta es preguntarse qué necesitará el modelo para informar al usuario, y devolver solo eso.
Puntos clave
- El decorador
@app.tool()genera automáticamente el esquema JSON de los parámetros - El nombre de la función = nombre de la herramienta (verbo + objeto)
- La docstring es crucial: guía al modelo sobre cuándo y cómo llamar a la herramienta
- Usa anotaciones de tipo de Python para el esquema (str, int, float, bool, list, dict)
- Valida siempre las entradas y devuelve errores accionables
- Devuelve JSON estructurado con valores legibles por humanos