El skill que arma servidores MCP que Claude sí sabe usar

Tienes un sistema interno, una API de pedidos, una base de datos Postgres, un script de deploy, y al final tú eres el cuello de botella: el agente pregunta, tú corres la query, tú pegas la salida de vuelta. El skill que arma servidores MCP cierra ese ciclo generando un servidor de Model Context Protocol para que Claude llame tu sistema directo, con herramientas reales y tipadas. Esta guía cubre qué hace el skill, cuándo exactamente conviene usarlo, cómo funciona por dentro, una invocación completa con la salida que deberías esperar, la configuración y los detalles que deciden si el agente usa bien tus herramientas o se traba con ellas.

Lo que conviene tener claro desde el arranque: un servidor MCP no es "exponerle mi API al modelo". Es diseñar una superficie de herramientas deliberada y acotada, un puñado de operaciones bien nombradas, bien descritas y validadas con rigor, sobre las que el modelo pueda razonar. El valor real del skill no está en el boilerplate; está en imponer esa disciplina para que no termines entregándole una shell cargada a un agente y llamándolo "integración".

01 · Qué hace el skill

El skill arma un servidor MCP que ya corre, partiendo de la descripción de tu sistema. Le dices "tengo un servicio de pedidos con endpoints de búsqueda, reembolso y estado" y te produce cuatro cosas, no una:

1. Definiciones de herramientas, el nombre, la descripción y el cableado que registra cada herramienta en el servidor.
2. Esquemas de entrada, argumentos tipados y validados (Zod en TypeScript, Pydantic en Python) para que una llamada mal formada falle antes de tocar tu backend.
3. Handlers, las funciones que de verdad llaman a tu API o a tu base de datos y le dan forma al resultado para el modelo.
4. Transport y punto de entrada, stdio para un setup local de Claude Desktop / Claude Code, o HTTP para uno remoto, más el snippet de config para registrarlo.

Lo que a propósito no hace es darle al agente una herramienta genérica tipo "corre este SQL" o "hazle curl a esta URL". Ese es justo el antipatrón que el skill existe para evitar. Una salida de emergencia sin filtros convierte en teatro cada propiedad de seguridad de MCP.

02 · Cuándo conviene usarlo

Este skill es para un momento específico, y sacarlo en el momento equivocado es esfuerzo perdido. Úsalo cuando se cumplan todas estas:

• Tienes un sistema real y persistente que el agente va a operar muchas veces, una API, una base de datos, un servicio interno, no una tarea desechable.
• Quieres que el agente lo llame a lo largo de muchas sesiones, por nombre, con argumentos que él mismo arma.
• Te importa el borde: permisos, validación, un registro auditable de qué se llamó.

No lo uses cuando:

• Es algo de una sola vez. Si solo necesitas resolver una query una vez, un script o un copy-paste te sale más barato que un servidor.
• La "herramienta" en realidad es un prompt. Reformatear texto o resumir no necesita MCP; necesita un buen prompt.
• Todavía no decidiste qué tiene permitido hacer el agente. MCP vuelve concretas las capacidades, así que una intención vaga termina en una superficie peligrosa.

Una regla práctica que ayuda: si te sentirías cómodo dándole a un contratista nuevo y capaz una lista corta de botones con nombre para apretar, y nervioso dándole la contraseña de la base de datos, esa es exactamente la forma que MCP busca.

03 · Cómo funciona por dentro

Un servidor MCP es un proceso de larga vida que habla Model Context Protocol sobre un transport. El handshake expone un manifiesto de herramientas; el cliente (Claude Code, Claude Desktop o tu propio loop de agente) lee ese manifiesto y, cuando el modelo decide actuar, manda un request de tool-call que el servidor enruta hasta tu handler.

El trabajo del skill es generar esa maquinaria como debe ser. Esta es la forma canónica que produce para una sola herramienta, las descripciones y el esquema son donde el skill se gana el sueldo:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
import { z } from "zod"
import { searchOrders } from "./orders.js"

const server = new McpServer({ name: "orders", version: "1.0.0" })

server.tool(
  "search_orders",
  "Find a customer's orders by their email address. Use this when the " +
    "user asks about a specific buyer's order history, a missing package, " +
    "or 'where is my order'. Do NOT use it for refunds — see refund_order.",
  {
    email: z.string().email().describe("The customer's email, exactly as on file"),
    limit: z.number().int().min(1).max(50).default(10),
  },
  async ({ email, limit }) => {
    const orders = await searchOrders(email, limit)
    if (orders.length === 0) {
      return {
        content: [{
          type: "text",
          text: "No orders for that email. The address may be mistyped, " +
                "or the buyer used a different one. Confirm the email and retry.",
        }],
      }
    }
    return { content: [{ type: "text", text: JSON.stringify(orders, null, 2) }] }
  },
)

await server.connect(new StdioServerTransport())

Ahí hay tres detalles que marcan la diferencia entre un servidor que el agente usa bien y uno con el que se enreda:

• La descripción lleva un "cuándo", un "qué" y un "no". El modelo lee las descripciones para escoger; gastar palabras en el borde ("Do NOT use it for refunds") evita el error de ruta más común.
• El esquema es estricto y se autodocumenta. «.email()» rechaza basura antes de que llegue a tu backend; «.max(50)» evita que el modelo pida diez mil filas; «.describe()» le da una pista campo por campo.
• El resultado vacío es un mensaje recuperable, no un silencio. El agente puede leer "the address may be mistyped", probar «search_customers» o preguntarle al usuario, de un arreglo vacío que tiene que adivinar no hay cómo recuperarse.

El handler es un traductor, no un pasamanos

El trabajo de un handler es llamar a tu sistema y luego darle forma al resultado pensando en que quien lo lee es un modelo. Eso significa recortar campos que el agente no necesita, formatear siempre igual y convertir las fallas en instrucciones. Un handler que devuelve el 500 pelado de tu API botó lo único que el agente necesitaba: qué hacer a continuación.

04 · Invocación de ejemplo y salida esperada

Invocas el skill como invocas cualquier skill de Claude Code, describiendo el trabajo en términos que hagan match con su trigger. Una descripción de verdad se lee como un brief, no como una orden:

/skill mcp-builder

Arma un servidor MCP para nuestro servicio interno de pedidos. Tiene tres
operaciones: buscar pedidos por email del cliente, traer un pedido por id y
emitir un reembolso (solo admin). El base URL viene de una env var.
TypeScript, transport stdio, esquemas Zod. Los reembolsos deben exigir un
motivo y no pueden pasar del total del pedido.

Lo que deberías recibir de vuelta no es prosa, es un scaffold que ya corre:

• Un archivo de servidor que registra search_orders, get_order y refund_order, cada uno con una descripción que arranca por la intención.
• Esquemas Zod por herramienta, donde la de reembolso exige un reason no vacío y valida el monto contra el total del pedido.
• Handlers que leen el base URL de una env var, llaman al servicio y devuelven errores que orientan ("order already refunded" en vez de un 409 a secas).
• El bloque de config exacto para registrar el servidor, más una nota de una línea con las env vars que tienes que definir.

Un ejemplo corto de la propia descripción del skill, el tipo de frontmatter que hace que se dispare con los requests correctos y se quede callado con el resto:

---
name: mcp-builder
description: Scaffold a Model Context Protocol server from a described
  system. Use when the user has an internal API, database, or service they
  want an agent to operate with real, typed tools. Produces tool defs,
  input schemas, handlers, transport, and the client config. Do NOT use for
  one-off scripts or prompt-only tasks.
---

Fíjate que la descripción sigue su propio consejo: dice cuándo usar el skill y cuándo no. Al skill que construye descripciones de herramientas más le vale escribir una buena para sí mismo.

05 · Configuración y registro

Un scaffold no sirve de nada hasta que el cliente sepa que existe. Para un servidor stdio local, el registro es un bloque JSON chico que el skill emite junto al código:

{
  "mcpServers": {
    "orders": {
      "command": "node",
      "args": ["./dist/orders-server.js"],
      "env": { "ORDERS_BASE_URL": "https://internal.example.com" }
    }
  }
}

Algunas decisiones de configuración que toma el skill, y por qué:

• Transport. Stdio para setups locales de un solo usuario (Claude Code en tu máquina); HTTP cuando el servidor es remoto o compartido. El skill arranca por stdio porque la mayoría de los primeros servidores son locales, y pregunta antes de asumir HTTP.
• Secretos por env, nunca en el código. Los base URLs y tokens vienen de variables de entorno, esto va de la mano con cómo manejo las credenciales en el gestor de secretos Infuse y en Agent Orchestra: nada sensible cae en el repo, y el servidor lee del entorno que le inyecta el host.
• Permisos por herramienta. Una herramienta solo-admin como refund_order se controla en el handler, no solo se rotula en la descripción. La descripción es apenas una pista para el modelo; el control de verdad es el otro.

06 · Trampas que muerden

Estas son las fallas que más veo, más o menos en orden de qué tan seguido pegan:

1. Descripciones vagas. Es la causa número uno de que un agente llame la herramienta equivocada. "Busca pedidos" no le dice nada al modelo sobre el cuándo. Gasta las palabras en el trigger y en el borde, no solo en el verbo.
2. Errores de los que el agente no puede recuperarse. Un 500 o un arreglo vacío es un callejón sin salida. "Email no encontrado, prueba primero con search_customers" deja que el agente replanee. Trata cada ruta de error como una oportunidad de orientar.
3. Demasiadas herramientas. Un servidor con treinta herramientas hace que el modelo gaste su presupuesto decidiendo en vez de haciendo. Mantén la superficie chica; junta las casi-duplicadas; separa solo cuando las intenciones de verdad difieren.
4. Salida que se desborda. Devolver la respuesta completa de tu API bota tokens y datos personales que el agente no necesita. El handler debe recortar a lo que el modelo realmente usa.
5. Tratar la descripción como control de acceso. Ya lo vimos arriba y vale repetirlo: los permisos viven en el handler.
6. Olvidar que es un proceso de larga vida. Un servidor MCP mantiene conexiones y estado. Maneja las reconexiones y el apagado; un servidor que se muere en silencio deja al agente llamando al vacío.

Una prueba chica que pesca casi todas: lee el nombre y la descripción de cada herramienta fuera de contexto, tal como lo hará el modelo. Si tú no puedes decir cuándo llamarla y cuándo no, el agente tampoco, y ningún handler ingenioso arregla una herramienta que el modelo nunca escoge bien.

Vale la pena echar mano del skill en cuanto notes que tú eres el cuello de botella entre un agente y un sistema que debería operar directo. Bien usado, te da un borde limpio y auditable: unas pocas herramientas con intención clara, validación estricta y errores que orientan. Mal usado, una herramienta «execute» genérica, descripciones vagas, permisos que solo viven en la prosa, apenas le pone ropa de protocolo al acceso crudo, y vas a gastar más tiempo depurando errores de ruta del que ahorraste.