mcp-builder: la skill de Anthropic para crear un servidor MCP con Claude Code

mcp-builder es la skill del repositorio oficial de Anthropic que enseña a Claude Code a crear servidores MCP (Model Context Protocol): el "enchufe" que permite que Claude, Cursor o cualquier agente consulten tu base de datos, tu API o tus hojas de cálculo con herramientas propias. Con ella, Claude investiga el protocolo, escribe el servidor en TypeScript o Python, lo prueba y prepara un examen de 10 preguntas para medir si un modelo sabe usarlo.

En el repaso de las 19 skills oficiales de Anthropic la dejamos pendiente. Aquí la pusimos a trabajar: leímos sus 4.086 líneas (commit 2c5958e, del 6 de noviembre de 2026) y le pedimos a Claude Code que creara un servidor MCP para una pequeña tienda de café. Tardó 99 segundos y costó 0,25 USD. Luego conectamos ese servidor a Claude y respondió una pregunta de negocio real por 0,067 USD. Por el camino encontramos dos fallos de la skill que te van a pasar a ti también: su guía de Python y su script de evaluación no funcionan con la versión actual del SDK.

Qué es un servidor MCP y para qué lo quieres

MCP es un estándar abierto para conectar modelos de IA con herramientas y datos. Un servidor MCP es un programa pequeño que expone funciones con nombre, descripción y parámetros (por ejemplo tienda_ver_stock_critico(umbral)), y un cliente (Claude Code, Claude Desktop, Cursor) las ofrece al modelo para que las llame cuando le hagan falta.

Para un negocio pequeño, esto significa poder preguntar en lenguaje normal "¿qué tengo que reponer?" o "¿qué pedidos de Ana siguen pendientes?" y que el agente consulte tus datos reales en lugar de inventar. Para un desarrollador, es la forma estándar de dar a un agente acceso a una API interna sin pegarle la documentación en el chat.

Si te preocupa la seguridad de conectar agentes a tus datos, lee antes cómo evitar la prompt injection en agentes de IA: un servidor MCP es justo la puerta por la que entra.

Qué trae la skill mcp-builder

La skill vive en skills/mcp-builder de anthropics/skills y tiene licencia Apache-2.0: puedes copiarla, adaptarla y usarla en proyectos comerciales conservando el aviso de licencia.

Las ideas de diseño que más valen la pena, y que Claude aplicó sin que se lo pidiéramos:

• Nombres con prefijo del servicio: tienda_buscar_productos y no buscar_productos, porque tu servidor convivirá con otros.
• Errores que dicen qué probar: en vez de "no encontrado", "Sin pedidos para ese filtro. Clientes: Ana, Diego… Estados: entregado, pagado, pendiente".
• Anotaciones readOnlyHint, destructiveHint, idempotentHint y openWorldHint en cada herramienta. Son pistas para el cliente, no una barrera de seguridad.
• Paginación con limit, has_more y next_offset, de 20 a 50 elementos por defecto, para no llenar el contexto del modelo.
• Transporte: stdio para servidores locales y Streamable HTTP sin estado para remotos. SSE está obsoleto.

Instalar mcp-builder en Claude Code

Tienes dos formas. Solo esta skill, con la CLI de skills.sh:

npx skills add anthropics/skills --skill mcp-builder --agent claude-code -y

O el plugin example-skills completo, que trae 12 skills de ejemplo, mcp-builder incluida:

/plugin marketplace add anthropics/skills
/plugin install example-skills@anthropic-agent-skills

Nosotros hicimos lo más simple: copiar la carpeta skills/mcp-builder del repositorio a .claude/skills/mcp-builder del proyecto. Claude Code la detecta al arrancar.

La prueba: un servidor MCP para una tienda de café

Creamos un proyecto vacío con dos CSV de una tienda ficticia: datos/productos.csv (10 productos con SKU, precio y stock) y datos/pedidos.csv (10 pedidos con cliente y estado). Y lanzamos Claude Code sin interfaz:

claude -p "Usa la skill mcp-builder. Crea un servidor MCP en Python (FastMCP, transporte stdio) llamado tienda_mcp para la pequeña tienda de café cuyos datos están en datos/productos.csv y datos/pedidos.csv. Solo lectura. Debe permitir buscar productos, ver stock bajo o agotado y consultar pedidos por cliente o estado. Crea el entorno con uv en .venv, instala dependencias, compílalo con py_compile y pruébalo arrancándolo. No hagas la fase de evaluaciones con la API." \
  --model sonnet \
  --allowedTools "Read,Write,Edit,Glob,Grep,Bash(uv:*),Bash(python:*),Bash(.venv/bin/python:*)"

Pedimos Python a propósito, aunque la skill recomienda TypeScript, porque es lo que más se usa para scripts de negocio. Resultado: 14 turnos, 99 segundos, 0,25 USD con Sonnet 5.5. Según el registro de la sesión, Claude cargó la skill, leyó solo la guía de Python (no las de TypeScript ni la de evaluación) y escribió tienda_mcp.py con tres herramientas:

Así queda una de ellas. Fíjate en el esquema Pydantic con descripciones y límites, y en las anotaciones:

from mcp.server.fastmcp import FastMCP
from pydantic import BaseModel, ConfigDict, Field

mcp = FastMCP("tienda_mcp")

RO = {"readOnlyHint": True, "destructiveHint": False,
      "idempotentHint": True, "openWorldHint": False}


class StockInput(BaseModel):
    model_config = ConfigDict(extra="forbid")
    umbral: int = Field(default=10, ge=0, le=10000,
                        description="'Stock bajo' = stock <= umbral (por defecto 10)")
    incluir_agotados: bool = Field(default=True, description="Incluir productos con stock 0")


@mcp.tool(name="tienda_ver_stock_critico", annotations={"title": "Ver stock bajo o agotado", **RO})
async def tienda_ver_stock_critico(params: StockInput) -> str:
    """Lista productos agotados (stock 0) y/o con stock bajo (<= umbral), de menor a mayor stock."""
    res = []
    for p in sorted(_productos(), key=lambda p: p["stock"]):
        if p["stock"] == 0 and params.incluir_agotados:
            res.append({**p, "situacion": "agotado"})
        elif 0 < p["stock"] <= params.umbral:
            res.append({**p, "situacion": "bajo"})
    return _json(res, umbral=params.umbral)


if __name__ == "__main__":
    mcp.run(transport="stdio")

Fallo 1: la guía de Python no funciona con mcp 2.x

El primer intento de Claude falló. uv pip install "mcp[cli]" instaló mcp 2.3.0, la versión actual en PyPI (la 2.0.0 salió en julio de 2026), y en la serie 2.x FastMCP ya no existe: se renombró a MCPServer. Lo comprobamos aparte en un entorno limpio:

ModuleNotFoundError: No module named 'mcp.server.fastmcp'. This is mcp 2.x,
where FastMCP was renamed to MCPServer (from mcp.server.mcpserver import MCPServer)
and other APIs changed; see the migration guide ... or pin 'mcp<2' to keep running v1 code.

La guía python_mcp_server.md de la skill usa from mcp.server.fastmcp import FastMCP en todos sus ejemplos y no fija versión. Claude lo resolvió solo: bajó a mcp[cli]<2 (quedó la 1.30.0) y lo dejó escrito en requirements.txt. Tú haz lo mismo o pide desde el principio la versión 2 con MCPServer. Curiosamente, la parte de TypeScript sí está al día: distingue el SDK v1 del v2 y ofrece un *codemod* para migrar.

Una lección de paso: python -m py_compile no detecta este error. Solo revisa la sintaxis; el import roto aparece al arrancar. La fase 3 de la skill sugiere py_compile para Python, así que arranca siempre el servidor de verdad o lista sus herramientas con un cliente.

Fallo 2: el script de evaluación también se rompe

La fase 4 usa scripts/evaluation.py, que importa connections.py. Su requirements.txt pide anthropic>=0.39.0 y mcp>=1.1.0, así que una instalación limpia trae mcp 2.3.0 y el script muere al importar:

ImportError: cannot import name 'streamablehttp_client' from 'mcp.client.streamable_http'

Con mcp<2 el import funciona. Además, si no le pasas -m, el script usa el modelo claude-3-7-sonnet-20250219, que ya está retirado. Instálalo así y elige un modelo actual:

pip install anthropic "mcp<2"
export ANTHROPIC_API_KEY=tu_clave
python scripts/evaluation.py -t stdio -c python -a tienda_mcp.py -m claude-haiku-5-5 evaluacion.xml

No ejecutamos la evaluación completa: cobra por la API de Anthropic aparte de tu suscripción de Claude Code, y para un servidor de tres herramientas no compensa. Para un servidor que vayas a publicar o vender, sí.

Conectar el servidor a Claude Code

Un servidor MCP no sirve de nada hasta que un cliente lo usa. Creamos mcp.json con la ruta al Python del entorno y al script:

{
  "mcpServers": {
    "tienda": {
      "command": "/ruta/al/proyecto/.venv/bin/python",
      "args": ["/ruta/al/proyecto/tienda_mcp.py"]
    }
  }
}

Para tenerlo siempre disponible en Claude Code, en lugar de un archivo puedes registrarlo con claude mcp add tienda -- /ruta/al/proyecto/.venv/bin/python /ruta/al/proyecto/tienda_mcp.py. Nosotros usamos el archivo y le hicimos una pregunta de negocio:

Claude llamó a dos herramientas, tienda_ver_stock_critico sin parámetros y tienda_consultar_pedidos con estado: "pendiente", y cruzó los datos: hay dos productos agotados, tres con stock bajo, y solo el café Loja 500 g tiene pedidos pendientes (P-1004 y P-1010, 4 unidades de 8 en stock). Lo comprobamos a mano contra los CSV y es correcto.

Un detalle de Claude Code: las herramientas MCP no se cargan en el contexto de entrada. Claude las busca con ToolSearch cuando las necesita, así que tener varios servidores conectados apenas gasta tokens hasta que se usan.

Cuánto cuesta crear un servidor MCP con mcp-builder

La comparación útil aquí no es con otra herramienta, sino con hacerlo a mano. Un desarrollador que no conoce el SDK tarda fácilmente una tarde en leer la especificación, elegir transporte y escribir esquemas, errores y anotaciones como los de arriba. La skill condensa todo eso, y Claude lo aplicó en minuto y medio por veinticinco céntimos.

Nuestra recomendación para gastar lo mínimo: servidor local por stdio mientras solo lo uses tú, Python con mcp<2 (o TypeScript v2 si empiezas de cero), sin evaluación por API hasta que el servidor vaya a usarlo otra gente, y un VPS barato solo cuando de verdad necesites acceso remoto.

Errores frecuentes

No module named 'mcp.server.fastmcp'. Tienes mcp 2.x. Fija mcp[cli]<2 o migra a from mcp.server.mcpserver import MCPServer.

cannot import name 'streamablehttp_client'. Lo mismo, pero en evaluation.py. Instala mcp<2 en el entorno del script.

El servidor stdio no responde o el cliente dice que el JSON es inválido. Algo escribe en la salida estándar. En un servidor stdio, los print y los logs van a stderr; la salida estándar es solo para el protocolo.

Claude Code no ve las herramientas. Usa rutas absolutas en mcp.json y el Python del entorno virtual, no el del sistema. En claude -p permite las herramientas con --allowedTools "mcp__tienda".

La skill no se activa. Nómbrala en el prompt ("usa la skill mcp-builder") o invócala con /mcp-builder.

El servidor funciona en local pero no lo quieres exponer. Si usas HTTP en tu máquina, enlázalo a 127.0.0.1, no a 0.0.0.0, y valida la cabecera Origin, como pide la guía de buenas prácticas de la skill.

Preguntas frecuentes

¿Python o TypeScript?

La skill recomienda TypeScript con el SDK v2, y es la parte de su documentación más al día. Python va igual de bien para leer CSV, bases de datos o APIs internas, siempre que fijes la versión del SDK.

¿Puedo conectar el servidor a Claude Desktop o Cursor?

Sí. MCP es un estándar: el mismo tienda_mcp.py funciona en cualquier cliente compatible. Solo cambia dónde se declara (cada cliente tiene su archivo de configuración).

¿El servidor puede modificar datos?

Puede, pero el nuestro es de solo lectura a propósito. Si añades herramientas que escriben, márcalas con destructiveHint: true y deja que el cliente pida confirmación. Las anotaciones no protegen nada por sí solas.

¿Necesito la fase de evaluación?

Para uso propio, no: una prueba con preguntas reales como la nuestra basta. Las 10 preguntas sirven para comparar versiones del servidor o detectar herramientas que el modelo no entiende.

¿Es seguro instalar servidores MCP de otros?

Un servidor MCP ejecuta código en tu máquina con tus permisos. Revisa el código, como harías con una skill: para eso tienes SkillSpector y nuestra guía de skills de Claude Code.

Conclusión

mcp-builder convierte "quiero que Claude consulte mis datos" en un servidor MCP bien diseñado en minutos y por céntimos: nombres con prefijo, esquemas validados, errores útiles y anotaciones, sin que tengas que leer la especificación. Su punto débil es la versión: la guía de Python y el script de evaluación siguen escritos para mcp 1.x, y el SDK ya va por la 2.3. Fija mcp<2 y funciona.

Siguiente paso: instálala con npx skills add anthropics/skills --skill mcp-builder, elige la hoja de cálculo o la API que más consultas a mano y pídele a Claude un servidor de solo lectura para ella. Y si además quieres que Claude pruebe tu web, sigue con webapp-testing.