Definición de Herramientas Llamables en un Servidor MCP

Una herramienta llamable es la forma más directa en que un servidor MCP le da algo que hacer a un modelo.

Configurar una herramienta correctamente significa que el modelo puede encontrarla, entender qué hace, llamarla con argumentos válidos y dar sentido a lo que regresa.

Resumen

Una herramienta en el SDK de Python de MCP comienza como una función ordinaria decorada con @mcp.tool().

El nombre de la función, sus parámetros con anotaciones de tipo y su cadena de documentación (docstring) se convierten conjuntamente en el esquema que un cliente utiliza para decidir cuándo y cómo llamarla.

Los manejadores deben ser estrechos y predecibles, haciendo un trabajo bien hecho en lugar de ramificarse en varios comportamientos no relacionados basándose en un argumento de bandera.

Los errores deben elevarse como excepciones con un mensaje claro, no ser suprimidos o devueltos como cadenas ambiguas, para que el modelo obtenga retroalimentación útil cuando una llamada falla.

Las entradas estructuradas y validadas (a través de modelos Pydantic o anotaciones de tipo simples) detectan argumentos incorrectos antes de que su código de manejo se ejecute.

Receta

from mcp.server.fastmcp import FastMCP
 
mcp = FastMCP("tool-recipes")
 
@mcp.tool()
def get_weather(city: str, units: str = "celsius") -> str:
    """Obtener el clima actual de una ciudad.
 
    Args:
        city: El nombre de la ciudad, por ejemplo, "Austin" o "Tokio".
        units: "celsius" o "fahrenheit". Predeterminado a "celsius".
    """
    if units not in ("celsius", "fahrenheit"):
        raise ValueError('units debe ser "celsius" o "fahrenheit"')
    return f"72 grados {units} y soleado en {city}"

Cuándo recurrir a esto:

• El modelo necesita realizar una acción o cálculo, no solo leer datos estáticos.
• La operación tiene un conjunto pequeño y bien tipado de entradas que se mapean limpiamente a los parámetros de la función.
• Desea que la misma capacidad sea accesible desde Claude Code, Claude Desktop o una aplicación SDK de Agente personalizada sin reescribirla por cliente.
• El resultado de la llamada debe formar parte de la conversación, no solo ser almacenado en caché o mostrado por separado.

Ejemplo de Trabajo

# server.py
from typing import Literal
 
from mcp.server.fastmcp import FastMCP
from pydantic import BaseModel, Field
 
mcp = FastMCP("task-tools")
 
# Almacén en memoria para este ejemplo; reemplace con una base de datos real en producción.
_tasks: dict[int, dict] = {}
_next_id = 1
 
 
class CreateTaskInput(BaseModel):
    title: str = Field(..., min_length=1, max_length=200, description="Título corto de la tarea")
    priority: Literal["low", "medium", "high"] = Field(
        "medium", description="Nivel de prioridad de la tarea"
    )
 
 
@mcp.tool()
def create_task(input: CreateTaskInput) -> str:
    """Crear una nueva tarea y devolver su id.
 
    Úselo cuando el usuario pida añadir, seguir o recordar un elemento de la lista de tareas pendientes.
    """
    global _next_id
    task_id = _next_id
    _next_id += 1
    _tasks[task_id] = {"title": input.title, "priority": input.priority, "done": False}
    return f"Tarea creada {task_id}: {input.title} (prioridad: {input.priority})"
 
 
@mcp.tool()
def complete_task(task_id: int) -> str:
    """Marcar una tarea existente como completada.
 
    Args:
        task_id: El id numérico devuelto por create_task.
    """
    task = _tasks.get(task_id)
    if task is None:
        raise ValueError(f"No se encontró ninguna tarea con el id {task_id}")
    task["done"] = True
    return f"Tarea {task_id} ({task['title']}) marcada como completada"
 
 
@mcp.tool()
def list_tasks(only_open: bool = True) -> str:
    """Listar las tareas seguidas.
 
    Args:
        only_open: Si es True, ocultar las tareas ya marcadas como completadas. Predeterminado a True.
    """
    rows = [
        f"#{tid} [{t['priority']}] {t['title']}{' (completada)' if t['done'] else ''}"
        for tid, t in _tasks.items()
        if not (only_open and t["done"])
    ]
    return "\n".join(rows) if rows else "No se encontraron tareas."
 
 
if __name__ == "__main__":
    mcp.run(transport="stdio")

Lo que esto demuestra:

• Tres herramientas estrechas y de propósito único (create_task, complete_task, list_tasks) en lugar de una herramienta con un indicador mode.
• Un modelo Pydantic (CreateTaskInput) que valida una entrada estructurada con una restricción de longitud y un conjunto restringido de valores permitidos.
• Un tipo Literal que restringe priority a exactamente tres cadenas válidas, aplicado antes de que se ejecute el cuerpo del manejador.
• Manejo de errores consistente: los ids desconocidos elevan ValueError con un mensaje que nombra el problema específico.
• Devoluciones de cadenas simples que se leen de forma natural cuando el modelo las presenta en una conversación.

Inmersión Profunda

Cómo Funciona

• Cuando el servidor se inicia, FastMCP inspecciona cada función decorada con @mcp.tool() y construye un Esquema JSON a partir de sus anotaciones de tipo y valores predeterminados.
• La cadena de documentación (docstring) de la función se convierte en la descripción de la herramienta; el cliente muestra esto al modelo para que pueda juzgar cuándo la herramienta es relevante.
• Cuando un cliente llama a list_tools(), recibe este esquema y descripción para cada herramienta registrada, sin que usted escriba ningún esquema a mano.
• Cuando el modelo decide llamar a una herramienta, el cliente envía el nombre de la herramienta más un objeto JSON de argumentos; el SDK valida ese objeto contra el esquema generado antes de invocar su función.
• Si la validación falla (tipo incorrecto, campo requerido faltante, valor fuera de un conjunto Literal), el SDK devuelve un error de esquema al cliente sin llamar nunca a su manejador.

Reglas de Nomenclatura y Descripción de un Vistazo

Notas de Python

# Prefiera un tipo restringido sobre una cadena suelta cuando el conjunto válido sea pequeño y conocido.
from typing import Literal
 
@mcp.tool()
def set_status(status: Literal["open", "in_progress", "closed"]) -> str:
    """Establecer el estado del elemento actual."""
    return f"Estado establecido a {status}"
 
# Para validación más rica (rangos, formatos, campos anidados), use un modelo Pydantic
# como parámetro único, como se muestra en CreateTaskInput arriba.

Parámetros y Valores de Retorno

Trampas Comunes

• Nombres de herramientas vagos como handle o process. El modelo no tiene nada con qué emparejar la intención. Solución: use un nombre específico, que comience con un verbo, como create_task o send_email.
• Una herramienta con un parámetro de cadena mode o action que se ramifica en comportamientos no relacionados. Esto confunde el descubrimiento basado en esquemas y aumenta la probabilidad de una llamada incorrecta. Solución: divídalo en herramientas separadas y de alcance estrecho.
• Devolver None o una cadena vacía en caso de fallo en lugar de elevar una excepción. El modelo no tiene señal de que algo salió mal y puede informar incorrectamente del éxito. Solución: eleve una excepción con un mensaje específico; deje que el SDK la traduzca a un error de herramienta.
• Docstrings faltantes o delgados. Sin una descripción, el modelo está adivinando lo que hace una herramienta basándose solo en su nombre. Solución: incluya siempre un resumen de una línea más un bloque Args:.
• Omitir la validación de entrada en rangos numéricos o de cadenas. Un manejador que confía ciegamente en sus entradas puede fallar en casos extremos como recuentos negativos o cadenas vacías. Solución: use Literal, restricciones Field de Pydantic o comprobaciones explícitas al principio del manejador.
• Mutar estado global compartido sin ninguna protección. Dos llamadas rápidas de herramientas contra el mismo almacén en memoria pueden competir o corromper datos. Solución: use un almacén de datos real con transacciones, o agregue bloqueo, una vez que supere una demostración.

Alternativas

Preguntas Frecuentes

@mcp.tool()
def withdraw(account_id: str, amount: float) -> str:
    """Retirar fondos de una cuenta."""
    if amount <= 0:
        raise ValueError("el monto debe ser positivo")
    return f"Retirados {amount} de {account_id}"

Relacionados

• Entendiendo MCP: Herramientas, Recursos y Prompts - la base conceptual de lo que es una herramienta frente a un recurso o un prompt.
• Conceptos Básicos del Núcleo de MCP - un servidor y cliente mínimo de una sola herramienta sobre el cual construir.
• Exposición de Datos Legibles como Recursos MCP - el primitivo hermano para datos de solo lectura.
• Comparación de Herramientas, Recursos y Prompts de MCP - decidir cuándo una capacidad pertenece como herramienta en absoluto.
• Mejores Prácticas de Conceptos Básicos del Núcleo de MCP - una lista de verificación para la calidad del esquema y la nomenclatura.

Versiones de Stack: Escrito contra la línea de modelos Claude actual a partir de ~junio de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (el predeterminado), y Claude Haiku 4.5 - y la especificación actual del Protocolo de Contexto del Modelo. Los nombres de los modelos, las versiones del SDK y la especificación MCP se mueven rápidamente: verifique los detalles actuales en platform.claude.com/docs y modelcontextprotocol.io antes de confiar en ellos.