mcp-server-template

Un punto de partida listo para producción para un servidor MCP.

La guía de inicio rápido de la documentación de MCP te da una herramienta funcionando en diez líneas. Esto es lo que terminas añadiendo durante las tres semanas siguientes, una vez que algo que no controlas llama a esa herramienta.

@mcp.tool()
def add(a: int, b: int) -> int:
    return a + b          # fine on a laptop

Lo que falta ahí no son funciones. Es lo que ocurre cuando la herramienta se cuelga, lanza una excepción, devuelve una novela o recibe cuarenta llamadas a la vez — y qué se le permite ver al modelo cuando eso sucede.

El problema que esto resuelve

Quien llama a una herramienta MCP es un modelo de lenguaje, lo que cambia la ingeniería.

• Un modelo no puede leer un stack trace, pero lo repetirá encantado a tu usuario. Así que un traceback filtrado es a la vez inútil y una divulgación.

• Un modelo tiene su propio plazo límite. Una herramienta que se cuelga no produce una respuesta lenta; produce una conversación muerta.

• Un modelo no puede distinguir un resultado truncado de uno completo. Desbordar su contexto en silencio no lanza un error: degrada la respuesta, y te enteras por un cliente.

• Un modelo reintentará si se lo permites. Así que «no encontrado» y «el upstream está caído» tienen que ser respuestas distintas, o castigará a un servicio por un registro que nunca existió.

Cada uno de esos problemas se gestiona una sola vez, en un solo lugar, de modo que una herramienta añadida un viernes por la tarde hereda las mismas protecciones que una que se escribió con cuidado el primer día.

Related MCP server: Graft

Lo que obtienes

Inicio rápido

git clone https://github.com/muhammadwaqasmbd/mcp-server-template
cd mcp-server-template
make install
make test
make run          # stdio, ready for a desktop MCP client

También se puede servir por red:

TRANSPORT=streamable-http PORT=8000 python -m mcp_server_template

Apunta hacia él un cliente de escritorio

{
  "mcpServers": {
    "template": {
      "command": "python",
      "args": ["-m", "mcp_server_template"],
      "cwd": "/absolute/path/to/mcp-server-template"
    }
  }
}

Añadir tu propia herramienta

Escribe la función. Nada más.

# src/mcp_server_template/tools/orders.py
from ..errors import InvalidInput, UpstreamUnavailable

async def cancel_order(order_id: str) -> dict:
    """Cancel an order. Returns the order's new state."""
    if not order_id.strip():
        raise InvalidInput("order_id must not be empty")     # model can fix this
    ...
    raise UpstreamUnavailable("order service timed out")     # model may retry

Regístrala detrás del guard:

mcp.tool(name="cancel_order", description="Cancel an order by id.")(
    guard.wrap(orders.cancel_order)
)

Ahora ya tiene el tiempo de espera, el límite de concurrencia, la barrera de errores, el truncamiento y el registro. Y no ha tenido que escribir ni gota de eso.

Lanza InvalidInput cuando el modelo pueda arreglarlo. Lanza UpstreamUnavailable cuando reintentar pueda funcionar. Devuelve algo normal para los resultados que son simplemente false — un registro que no existe es una respuesta, no una excepción.

Arquitectura

server.py      the ONLY module that imports the MCP SDK
   │
   ├── guard.py          timeout · concurrency · error boundary · truncation · timing
   ├── errors.py         what a model is allowed to see, and secret redaction
   ├── observability.py  JSON logs on stderr, correlation ids
   ├── config.py         validated once at boot, immutable thereafter
   └── tools/            plain functions. No protocol knowledge. No decorators

La flecha de dependencia apunta en una sola dirección: que las herramientas no saben nada de MCP, y que el guard no sabe nada de tus herramientas. Por eso las pruebas levan en milisegundos sin servidor y por eso un cambio en el SDK toca exactamente un solo archivo.

Lo que deliberadamente no hace

Ser sincero con las limitaciones es más útil que una lista más larga de funcionalidades.

• Sin autenticación. Por stdio, la seguridad con el sistema operativo es causada por el límite. Si lo expones por HTTP, pon delante autenticación real — el SDK lo soporta, y conectarlo aquí supondría un modelo de amenazas aún para decidir.

• No hay lógica de reintentos dentro de las herramientas. El guard informa de si blow falla es reintable; decidir reintentar corresponde al llamante, que tiene el contexto y el presupuesto.

• Sin límite de tasa por llamante. El límite de concurrencia acota el trabajo total, no la equidad por identidad. Si lo necesitas, primero necesitas identidad.

• Sin persistencia, cola ni programador. Un servidor de herramientas que se convierte silenciosamente en un ejecutor de trabajo es un sistema distribuido que nos ha diseñado.

• Sin resultados parciales en streaming. Merece la pena añadirlo para herramientas de larga duración; se ha omitido porque complica la barrera de errores y la mayoría de las herramientas lo necesitan.

Pruebas

make test

La suite está hecha deliberadamente para el fallo, no para la cobertura. Declara que una herramienta colgada se cancela, que una excepción inesperada no puede filtrar su mensaje, que el resultado sobredimensionado se trunca visiblemente, que el límite de concurrencia aguanta bajo diez llamadas simultáneas, y que una herramienta sincronizada bloqueante se muera de hambre en el bucle de eventos.

Licencia

MIT — ver LICENSE.

Creado por Muhammad Waqas, que dedica la mayor parte de su tiempo a sistemas de agentes en las industrias reguladas, donde una respuesta errónea pero segura es un incidente que hay que informar.