Creación de un servidor MCP con el SDK de Python

El SDK oficial de Python para MCP te proporciona un pequeño conjunto de decoradores para registrar herramientas, recursos y prompts.

Todo lo demás, como la conexión, la negociación de capacidades y el enrutamiento de solicitudes, se maneja por ti.

Resumen

Un servidor MCP de Python se construye alrededor de FastMCP, la clase de servidor de alto nivel del SDK.

Registras capacidades con tres decoradores: @mcp.tool(), @mcp.resource() y @mcp.prompt().

Las anotaciones de tipo en cada función sirven como el esquema de entrada que el cliente ve durante la negociación de capacidades.

Los errores que se generan dentro de un manejador se convierten en respuestas de error estructuradas en lugar de bloquear el servidor.

Esta página se basa en el esqueleto mínimo de la página de conceptos básicos y profundiza en los argumentos tipados, los recursos parametrizados y el manejo de errores.

Receta

from mcp.server.fastmcp import FastMCP
 
mcp = FastMCP("tickets-server")
 
@mcp.tool()
def create_ticket(title: str, priority: str = "normal") -> str:
    """Crea un ticket de soporte y devuelve su ID."""
    return "T-1042"
 
@mcp.resource("tickets://{ticket_id}")
def get_ticket(ticket_id: str) -> str:
    """Recupera un ticket individual por ID."""
    return f"Ticket {ticket_id}: abierto"
 
@mcp.prompt()
def triage_prompt(ticket_id: str) -> str:
    return f"Revisa el ticket {ticket_id} y recomienda el siguiente paso."
 
if __name__ == "__main__":
    mcp.run(transport="stdio")

Cuándo recurrir a esto:

• Quieres exponer una API interna, base de datos o sistema de archivos a Claude como herramientas que se puedan llamar.
• Necesitas datos de solo lectura (configuración, documentación, registros) disponibles para un cliente sin que cuenten como una "acción".
• Quieres plantillas de prompt reutilizables compartidas entre todos los clientes que se conectan a este servidor.
• Estás construyendo primero para desarrollo local; stdio es el transporte adecuado antes de añadir una capa de red.

Ejemplo de trabajo

from dataclasses import dataclass
from mcp.server.fastmcp import FastMCP
 
mcp = FastMCP("tickets-server")
 
@dataclass
class Ticket:
    id: str
    title: str
    priority: str
    status: str
 
_tickets: dict[str, Ticket] = {
    "T-1": Ticket(id="T-1", title="Impresora sin conexión", priority="low", status="open"),
    "T-2": Ticket(id="T-2", title="Interrupción de VPN", priority="high", status="closed"),
}
_next_id = 3
 
 
@mcp.tool()
def create_ticket(title: str, priority: str = "normal") -> str:
    """Crea un nuevo ticket de soporte y devuelve su ID.
 
    La prioridad debe ser una de las siguientes: low, normal, high.
    """
    global _next_id
    if priority not in ("low", "normal", "high"):
        raise ValueError(f"prioridad no válida '{priority}', se esperaba low, normal o high")
 
    ticket_id = f"T-{_next_id}"
    _next_id += 1
    _tickets[ticket_id] = Ticket(id=ticket_id, title=title, priority=priority, status="open")
    return ticket_id
 
 
@mcp.tool()
def close_ticket(ticket_id: str) -> str:
    """Marca un ticket como cerrado."""
    ticket = _tickets.get(ticket_id)
    if ticket is None:
        raise ValueError(f"no existe ticket con id '{ticket_id}'")
    ticket.status = "closed"
    return f"{ticket_id} cerrado"
 
 
@mcp.resource("tickets://{ticket_id}")
def get_ticket(ticket_id: str) -> str:
    """Recupera los detalles de un ticket individual por ID."""
    ticket = _tickets.get(ticket_id)
    if ticket is None:
        raise ValueError(f"no existe ticket con id '{ticket_id}'")
    return f"{ticket.id} [{ticket.priority}] {ticket.title} - {ticket.status}"
 
 
@mcp.resource("tickets://open")
def list_open_tickets() -> str:
    """Lista todos los tickets abiertos."""
    open_ids = [t.id for t in _tickets.values() if t.status == "open"]
    return "\n".join(open_ids) if open_ids else "no hay tickets abiertos"
 
 
@mcp.prompt()
def triage_prompt(ticket_id: str) -> str:
    """Crea un prompt pidiendo una recomendación de triaje para un ticket."""
    return f"Revisa el ticket {ticket_id} y recomienda si escalarlo o cerrarlo."
 
 
if __name__ == "__main__":
    mcp.run(transport="stdio")

Lo que esto demuestra:

• Dos herramientas, create_ticket y close_ticket, que modifican el estado del lado del servidor y validan sus propias entradas antes de hacerlo.
• Un recurso parametrizado, tickets://{ticket_id}, junto a un recurso fijo, tickets://open, mostrando ambos estilos.
• Errores de validación generados como ValueError simples, que el SDK convierte en una respuesta de error estructurada en lugar de bloquear el proceso.
• Una plantilla de prompt que hace referencia a un ID de ticket, mantenida intencionalmente simple ya que los prompts deben permanecer declarativos.

Inmersión Profunda

Cómo funciona

• FastMCP("tickets-server") crea una instancia de servidor y conecta inmediatamente las etapas de conexión y negociación del ciclo de vida de la solicitud.
• Cada llamada a @mcp.tool() registra la función decorada en la tabla de herramientas interna del servidor, indexada por el nombre de la función a menos que se proporcione un nombre explícito.
• Las anotaciones de tipo y la cadena de documentación de la función se introspeccionan en el momento del registro para construir el esquema JSON que se envía a los clientes durante la negociación de capacidades.
• Cuando un cliente llama a una herramienta, el SDK valida los argumentos entrantes contra ese esquema antes de que se ejecute el cuerpo de tu función.
• Los recursos siguen el mismo patrón de registro pero se abordan por URI; un {placeholder} en la plantilla URI se convierte en un parámetro que se pasa a tu función.

Manejo de errores

Generar una excepción estándar de Python dentro de cualquier manejador es la forma correcta de señalar un fallo.

@mcp.tool()
def get_priority_multiplier(priority: str) -> float:
    multipliers = {"low": 0.5, "normal": 1.0, "high": 2.0}
    if priority not in multipliers:
        raise ValueError(f"prioridad desconocida '{priority}'")
    return multipliers[priority]

El SDK captura la excepción y la convierte en un resultado de error estructurado que el cliente puede mostrar o razonar, en lugar de dejar que bloquee el proceso del servidor.

Prefiere generar errores temprano con un mensaje claro en lugar de devolver una cadena como "error: entrada incorrecta", que el cliente trataría como un resultado exitoso.

Herramientas vs. Recursos vs. Prompts de un vistazo

Notas de Python

# Usa anotaciones de tipo precisas; se convierten en el esquema contra el cual el cliente valida.
@mcp.tool()
def set_priority(ticket_id: str, priority: str) -> str:
    ...
 
# Los argumentos opcionales con valores predeterminados se reflejan como opcionales en el esquema.
@mcp.tool()
def search_tickets(query: str, limit: int = 10) -> list[str]:
    ...

Las anotaciones de tipo precisas son más importantes aquí que en el código interno típico, ya que se convierten en parte de un contrato del que depende un cliente, no solo en documentación para otro desarrollador.

Parámetros y valores de retorno

Trampas comunes

• Anotaciones de tipo vagas producen un esquema inútil. Un parámetro tipado como str cuando en realidad es un conjunto fijo de valores (como priority) no da al cliente ninguna pista sobre las entradas válidas. Solución: valida contra un conjunto explícito dentro de la función y genera un ValueError claro, o usa una anotación de tipo Literal donde el SDK lo soporte.
• Devolver una cadena de error en lugar de generar una excepción. Devolver "error: no encontrado" de una herramienta parece un resultado exitoso para el cliente. Solución: genera una excepción; deja que el SDK la convierta en una respuesta de error adecuada.
• Modificar estado compartido sin protección para llamadas concurrentes. Un diccionario a nivel de módulo como _tickets puede ser modificado por solicitudes superpuestas si el servidor maneja más de una sesión. Solución: respalda el estado real con una base de datos u otra tienda segura para concurrencia una vez que hayas superado la prototipación local.
• Olvidar la cadena de documentación. Una herramienta sin cadena de documentación se registra bien pero no proporciona nada a Claude para razonar al decidir si llamarla. Solución: escribe siempre una cadena de documentación de una línea que describa lo que hace la herramienta y cualquier restricción en sus argumentos.
• Renombrar los argumentos de una herramienta en una versión posterior. Los clientes existentes que llaman a la herramienta con los nombres de argumento antiguos comenzarán a fallar la validación. Solución: trata los nombres de los argumentos como parte de tu contrato público y consulta las estrategias de versionado de esquemas antes de cambiarlos.
• Bloquear E/S dentro de un manejador. Una herramienta que realiza una llamada de red síncrona lenta bloquea el servidor para esa solicitud. Solución: usa async def para las funciones de herramienta que realizan E/S; el SDK soporta manejadores asíncronos directamente.

Alternativas

Preguntas frecuentes

@mcp.tool()
def divide(a: float, b: float) -> float:
    if b == 0:
        raise ValueError("no se puede dividir por cero")
    return a / b

Relacionado

• Conceptos básicos de servidores MCP - el esqueleto mínimo en el que se basa este artículo
• Cómo los servidores MCP manejan las solicitudes - el ciclo de vida en el que se integran estos manejadores
• Creación de un servidor MCP con el SDK de TypeScript - los mismos patrones en TypeScript
• Pruebas de servidores MCP antes del despliegue - ejercicio de estos manejadores con un cliente simulado
• Referencia de versionado y limitación de velocidad de esquemas de herramientas MCP - mantener los cambios de herramientas compatibles con versiones anteriores

Versiones de la pila: Escrito contra la línea de modelos de 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 los SDK actuales del Protocolo de Contexto del Modelo de Python/TypeScript. Los nombres de los modelos, las versiones de los SDK y la especificación MCP evolucionan rápidamente; verifica los detalles actuales en platform.claude.com/docs y modelcontextprotocol.io antes de confiar en ellos.