GSA MCP Hackathon — Plantilla de servidor

Un iniciador listo para ejecutar para construir un servidor Model Context Protocol (MCP) en Python, además de kits de despliegue para IBM Cloud (watsonx Orchestrate) y Databricks.

Construido con FastMCP y uv. Si nunca has construido un servidor MCP antes, comienza con QUICKSTART.md.

¿Qué es un servidor MCP?

Un servidor MCP expone herramientas (funciones que el modelo puede llamar), prompts (iniciadores de conversación reutilizables) y recursos (datos que el modelo puede leer) a un cliente de IA como Claude Desktop, Claude Code, o una plataforma de agentes como watsonx Orchestrate. Tú escribes las herramientas; el modelo del cliente decide cuándo llamarlas.

Esta plantilla te ofrece un servidor funcional con un ejemplo de cada uno, para que puedas reemplazar los ejemplos con tu propio servicio y desplegarlo.

Related MCP server: Python MCP Server Template

Estructura del repositorio

mcp-hackathon-template/
├── README.md                  # This file
├── QUICKSTART.md              # 5-minute clone → run → connect walkthrough
├── main.py                    # Local entry point (uv run python main.py)
├── pyproject.toml             # Package + dependencies (uv)
├── requirements.txt           # Mirror of runtime deps (for buildpack hosts)
├── Dockerfile                 # Container image (streamable-HTTP, port 8080)
├── manifest.yaml              # cloud.gov (Cloud Foundry) deploy
├── server.json                # MCP registry metadata
├── .env.example               # Copy to .env for local dev
├── .github/workflows/ci.yml   # Lint + test on push/PR
├── src/
│   └── example_server/        # ← rename to your service
│       ├── app.py             # Thin entry point: builds FastMCP, picks transport
│       ├── config.py          # Settings from env vars / .env
│       ├── models.py          # Pydantic models & enums for tool params
│       ├── utils.py           # Shared helpers (HTTP client, pagination)
│       ├── routes.py          # HTTP-only routes (/health, /version)
│       ├── tools/             # ONE FILE PER TOOL
│       │   ├── __init__.py    #   register_tools(mcp) aggregator
│       │   └── example_tool.py
│       ├── prompts/
│       │   ├── __init__.py    #   register_prompts(mcp) aggregator
│       │   └── example.py
│       └── resources/
│           ├── __init__.py    #   register_resources(mcp) aggregator
│           └── example.py
├── tests/                     # Import + registration smoke tests
├── eval/                      # Stub → build a Phoenix eval harness (see mcp-eval skill)
└── deploy/
    ├── README.md              # Which deployment kit to use
    ├── ibm/                   # watsonx Orchestrate: 3 kits (see below)
    └── databricks/            # Databricks Apps kit

Primeros pasos

Requisitos previos

• uv — pip install uv o brew install uv

Instalar y ejecutar

cp .env.example .env
uv sync
uv run python main.py

El servidor se inicia en modo stdio — habla JSON-RPC a través de stdin/stdout, que es como los clientes locales (Claude Desktop, Claude Code) lo lanzan. Consulta QUICKSTART.md para conectar un cliente.

Verificar

uv sync --group dev
uv run pytest tests/ -v      # tests
uv run ruff check .          # lint

El patrón de una herramienta por archivo

Cada herramienta vive en su propio archivo bajo src/example_server/tools/ y expone una función register(mcp). tools/__init__.py llama a cada una desde un único register_tools(mcp). Esto mantiene la lista de herramientas escaneable y te permite añadir o eliminar una integración tocando dos archivos.

Paso 1 — crea src/example_server/tools/my_tool.py:

from typing import Annotated
from fastmcp import FastMCP

from example_server.utils import fetch_json


def register(mcp: FastMCP) -> None:
    @mcp.tool(
        name="example_get_thing",
        annotations={
            "title": "Get a thing",
            "readOnlyHint": True,
            "destructiveHint": False,
            "idempotentHint": True,
            "openWorldHint": True,
        },
    )
    async def get_thing(thing_id: Annotated[str, "The ID to fetch."]) -> dict:
        """One-line summary. Document the data source, its update cadence,
        and the return shape here — the model reads this docstring."""
        return await fetch_json(f"https://api.example.gov/things/{thing_id}")

Paso 2 — conéctalo en tools/__init__.py:

from example_server.tools import example_tool, my_tool

def register_tools(mcp) -> None:
    example_tool.register(mcp)
    my_tool.register(mcp)  # ← add this line

Paso 3 — añade cualquier clave de API como campo tipado en config.py y documenta la variable de entorno en .env.example.

Los prompts (prompts/) y los recursos (resources/) siguen exactamente el mismo patrón de register(mcp) + agregador.

Renombrar el paquete

Antes de publicar tu servidor, renombra example_server a tu servicio (por ejemplo, census_mcp):

1. Renombra la carpeta src/example_server/ → src/<your_name>/.

2. Actualiza pyproject.toml: el [project].name, [project.scripts] y [tool.hatch.build.targets.wheel].packages.

3. Busca y reemplaza example_server en src/, tests/, main.py, Dockerfile y manifest.yaml.

Consejos de diseño de herramientas (datos federales)

• Devuelve datos estructurados, no prosa. Devuelve diccionarios/listas con claves consistentes y deja que el modelo narre.

• Documenta la frescura. Los conjuntos de datos federales van con retraso; indica la frecuencia de actualización y la fecha "as-of" en el docstring.

• Expón la paginación. Usa PaginationParams / paginate() de utils.py, y devuelve has_more / next_offset.

• Usa tiempos de espera explícitos. utils.fetch_json tiene un valor predeterminado de 30s.

• Errores accionables. Devuelve un diccionario de error con un hint, no un stack trace crudo.

Despliegue

El desarrollo local usa stdio. Para compartir tu servidor con una plataforma de agentes, despliégalo y regístralo. Consulta deploy/README.md para un selector, luego:

• IBM watsonx Orchestrate — deploy/ibm/ (tres kits: toolkit local stdio, Code Engine build-from-Git e imagen preconstruida).

• Databricks Apps — deploy/databricks/.

Ambos leen el mismo código de servidor; app.py sirve HTTP automáticamente cuando la plataforma inyecta un puerto.

Evaluaciones

Medir qué tan bien un LLM puede usar tus herramientas es la verdadera prueba de la calidad del servidor. Esta plantilla intencionalmente no incluye un marco de evaluación — consulta eval/README.md para saber cómo construir uno con la habilidad mcp-eval.

Licencia

MIT. Consulta SECURITY.md para la política de divulgación de vulnerabilidades y las notas de seguridad del hackathon.