Definiendo herramientas con MCP

Construir un servidor MCP se vuelve mucho más simple cuando usas el SDK oficial de Python para MCP. En lugar de escribir manualmente esquemas JSON complejos para las herramientas, puedes definirlas con decoradores y dejar que el SDK se encargue del trabajo pesado.



En este ejemplo, estamos creando un servidor MCP que gestiona operaciones con documentos. El servidor tendrá dos herramientas principales: una para leer el contenido de los documentos y otra para actualizarlos. Todos los documentos existen en memoria como un simple diccionario donde las claves son los IDs de los documentos y los valores son las cadenas de contenido.

Beneficios del SDK de Python para MCP

El proyecto MCP proporciona SDKs oficiales para construir servidores y clientes en múltiples lenguajes de programación. Usar el SDK de Python ofrece varias ventajas:

• Crea servidores MCP con un mínimo de código repetitivo
• Genera automáticamente esquemas JSON a partir de las firmas de funciones de Python
• Simplifica la definición de herramientas mediante decoradores
• Gestiona la validación de tipos y el manejo de errores



Así de fácil es definir una herramienta con el SDK. El decorador @mcp.tool, combinado con sugerencias de tipo y descripciones de campos, crea automáticamente el esquema de herramienta adecuado que Claude puede entender y usar.

Configurando el servidor

Este curso usa la versión 1 del SDK de Python para MCP. La importación de abajo falla en la versión 2, que renombró FastMCP. Si configuras el proyecto tú mismo, mantén el SDK por debajo de la versión 2:

uv add "mcp[cli]<2"

Con pip, la misma fijación de versión es pip install "mcp[cli]<2".

La configuración básica del servidor requiere solo unas pocas líneas:

from mcp.server.fastmcp import FastMCP
from pydantic import Field

mcp = FastMCP("DocumentMCP", log_level="ERROR")

docs = {
    "deposition.md": "This deposition covers the testimony of Angela Smith, P.E.",
    "report.pdf": "The report details the state of a 20m condenser tower.",
    "financials.docx": "These financials outline the project's budget and expenditures",
    "outlook.pdf": "This document presents the projected future performance of the system",
    "plan.md": "The plan outlines the steps for the project's implementation.",
    "spec.txt": "These specifications define the technical requirements for the equipment"
}

Implementando la herramienta de lectura

La primera herramienta permite a Claude leer el contenido de un documento proporcionando un ID de documento:

@mcp.tool(
    name="read_doc_contents",
    description="Read the contents of a document and return it as a string."
)
def read_document(
    doc_id: str = Field(description="Id of the document to read")
):
    if doc_id not in docs:
        raise ValueError(f"Doc with id {doc_id} not found")
    
    return docs[doc_id]

La definición de la herramienta incluye:

• Un nombre claro que describe la acción
• Una descripción que explica qué hace la herramienta
• Parámetros tipados con descripciones de campos
• Manejo de errores para IDs de documentos inválidos

Implementando la herramienta de edición

La segunda herramienta realiza operaciones simples de buscar y reemplazar en el contenido del documento:

@mcp.tool(
    name="edit_document",
    description="Edit a document by replacing a string in the documents content with a new string."
)
def edit_document(
    doc_id: str = Field(description="Id of the document that will be edited"),
    old_str: str = Field(description="The text to replace. Must match exactly, including whitespace."),
    new_str: str = Field(description="The new text to insert in place of the old text.")
):
    if doc_id not in docs:
        raise ValueError(f"Doc with id {doc_id} not found")
    
    docs[doc_id] = docs[doc_id].replace(old_str, new_str)

Esta herramienta toma tres parámetros: el ID del documento, el texto a buscar y el texto de reemplazo. La implementación usa el método integrado de Python replace() para cadenas, por simplicidad.

Detalles clave de implementación

Al definir herramientas con el SDK de MCP, recuerda estos puntos importantes:

• Importa Field de pydantic para agregar descripciones de parámetros
• Usa sugerencias de tipo para especificar los tipos de parámetros
• Incluye manejo de errores para casos extremos
• Escribe nombres y descripciones de herramientas claros y descriptivos
• El SDK de Python para MCP convierte automáticamente la firma de tu función en el esquema JSON adecuado

El SDK de Python para MCP reduce drásticamente la complejidad de crear herramientas en comparación con escribir manualmente esquemas JSON. Lo que antes requería docenas de líneas de definición de esquema ahora toma solo unas pocas líneas de funciones de Python decoradas.

El decorador @mcp.tool y su generación de esquemas basada en firmas provienen del SDK de Python para MCP. El Claude Agent SDK proporciona un decorador @tool separado para definir herramientas personalizadas, y espera un argumento explícito input_schema en lugar de anotaciones Field de pydantic en la firma de la función. En Python, ese esquema es un diccionario que asigna nombres de parámetros a tipos, como {"latitude": float}, que el Agent SDK convierte a JSON Schema por ti, o un diccionario completo de JSON Schema cuando necesitas enums, rangos, campos opcionales u objetos anidados. Cuando leas código de herramientas en otro lugar, verifica qué SDK importa, ya que los dos decoradores son fáciles de confundir.