Crear un servidor MCP se vuelve mucho más sencillo 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 documentos y otra para actualizarlo. Todos los documentos existen en memoria como un diccionario simple donde las claves son los ID de los documentos y los valores son las cadenas de contenido.
Ventajas del SDK de Python para MCP
El proyecto MCP ofrece SDKs oficiales para crear servidores y clientes en varios 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
- Maneja 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 (type hints) y descripciones de campos, crea automáticamente el esquema de herramienta adecuado que Claude puede entender y usar.
Configurar 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"
}Implementar 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 ID de documento inválidos
Implementar 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 replace() de las cadenas de Python por simplicidad.
Detalles clave de la implementación
Al definir herramientas con el SDK de MCP, recuerda estos puntos importantes:
- Importa
Fieldde pydantic para agregar descripciones de parámetros - Usa sugerencias de tipo (type hints) para especificar los tipos de los parámetros
- Incluye manejo de errores para casos límite
- 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 solía requerir 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 independiente(se abre en una pestaña nueva) 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 enumeraciones, rangos, campos opcionales u objetos anidados. Cuando leas código de herramientas en otro lugar, revisa qué SDK importa, ya que los dos decoradores son fáciles de confundir.