16. Servidores MCP y Skills

Objetivo del tema

Conectar Claude Code con servicios y datos externos mediante Model Context Protocol (MCP), gobernar esas capacidades con ámbitos, autenticación y permisos, y envolverlas en Skills que definan procedimientos repetibles. Al finalizar construiremos un flujo de diagnóstico que consulta tickets y documentación sin conceder acceso de escritura innecesario.

16.1 MCP aporta capacidad; una Skill aporta método

MCP es un protocolo abierto que permite a un cliente como Claude Code descubrir e invocar capacidades expuestas por servidores. Evita crear una integración específica para cada combinación de asistente y servicio. Un servidor puede conectar con un gestor de incidencias, una base de datos, documentación interna, un navegador o una API propia.

Conectar un servidor no enseña por sí solo el proceso del equipo. Si MCP entrega “buscar ticket” y “agregar comentario”, una Skill puede exigir primero leer el contexto, consultar el runbook, separar hechos de hipótesis y pedir confirmación antes de publicar.

Elegir el mecanismo adecuado

Necesidad	Mecanismo
Dar acceso estructurado a una API externa	Servidor MCP
Normalizar una investigación repetida	Skill
Aplicar reglas permanentes de arquitectura	CLAUDE.md
Reaccionar automáticamente a un evento	Hook
Aislar una investigación voluminosa	Subagente, opcionalmente con herramientas MCP

16.2 Modelo mental: herramientas, recursos y prompts

Los servidores pueden publicar tres clases principales de elementos. Comprenderlas evita tratar toda información como una operación con efectos secundarios.

Primitivas que puede ofrecer un servidor

Primitiva	Propósito	Ejemplo	Uso en Claude Code
Tool	Función invocable con un esquema de entrada.	get_ticket, add_comment	Claude la selecciona como herramienta y pasa argumentos estructurados.
Resource	Contenido identificado por URI.	runbook://payments/timeouts	Se referencia con @servidor:protocolo://ruta.
Prompt	Plantilla provista por el servidor.	review_incident	Aparece como comando /servidor:prompt.

16.3 Transportes: HTTP, stdio, WebSocket y SSE

Cómo se conecta Claude Code con un servidor

Transporte	Ubicación	Ventajas	Criterio
HTTP	Remota	Servicio centralizado, OAuth y despliegue independiente.	Opción habitual para SaaS y servicios corporativos.
stdio	Proceso local	Acceso directo a herramientas locales y desarrollo sencillo.	Usa ejecutables auditados y versiones fijadas.
WebSocket	Remota y persistente	Comunicación bidireccional y eventos iniciados por servidor.	Solo cuando se requiera conexión persistente; usa configuración JSON.
SSE	Remota	Compatibilidad con servidores antiguos.	Está deprecado; prefiere HTTP cuando exista.

# Servidor HTTP compartido con el proyecto
claude mcp add --transport http --scope project docs https://mcp.example.com/mcp

# Servidor stdio privado del proyecto actual
claude mcp add --transport stdio --scope local catalog -- python tools/catalog_server.py

# Todo lo que sigue a -- pertenece al proceso servidor
claude mcp add --transport stdio --scope local reports -- python tools/report_server.py --port 8090

En stdio, el separador -- evita que Claude Code interprete las opciones del servidor como propias. En Windows confirma qué comando abre el runtime real (python, py, una ruta absoluta o un ejecutable instalado). Para servidores que solo responden solicitudes, HTTP es preferible a una conexión persistente.

16.4 Ámbitos, archivos y precedencia

El ámbito determina dónde se guarda la definición, quién la recibe y qué riesgo de distribución existe.

Ámbitos de instalación MCP

Ámbito	Carga	Se comparte	Almacenamiento
local (predeterminado)	Proyecto actual	No	~/.claude.json, asociado al proyecto
project	Proyecto actual	Sí	.mcp.json en la raíz
user	Todos tus proyectos	No	~/.claude.json
Administrado	Según política organizativa	Por TI	managed-mcp.json del sistema

local en MCP no equivale a .claude/settings.local.json. Los servidores locales y de usuario se guardan en ~/.claude.json; la configuración compartida usa .mcp.json. Si un nombre se repite, la precedencia es local, proyecto, usuario, plugin y finalmente conectores de claude.ai.

{
  "mcpServers": {
    "support": {
      "type": "http",
      "url": "${SUPPORT_MCP_URL:-https://support.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${SUPPORT_API_TOKEN}"
      }
    }
  }
}

La expansión ${VAR} permite versionar estructura sin credenciales; ${VAR:-valor} agrega un predeterminado. Si una variable obligatoria no existe, la configuración no se procesa. Nunca reemplaces una referencia por el secreto real dentro de .mcp.json.

16.5 Instalar, inspeccionar y retirar servidores

Agregar una definición solo confirma que fue escrita. Comprueba además la conexión, autenticación, herramientas anunciadas y ámbito efectivo.

# Inventario y salud
claude mcp list
claude mcp get support

# Interfaz dentro de Claude Code
/mcp

# Retirar del ámbito exacto
claude mcp remove support --scope project

# Volver a decidir sobre servidores compartidos
claude mcp reset-project-choices

Un servidor de .mcp.json requiere aprobación en una sesión interactiva antes de usarse. Revisa nombre, comando o URL y variables solicitadas. Los estados pueden indicar conexión correcta, autenticación pendiente, rechazo o fallo; consulta claude mcp get <nombre> para el detalle.

16.6 Autenticación y secretos

Los servidores HTTP pueden usar OAuth 2.0. Agrégalos sin incrustar tokens y completa el inicio de sesión desde /mcp cuando aparezca “Needs authentication”:

claude mcp add --transport http --scope local sentry https://mcp.sentry.dev/mcp

claude
/mcp

Claude Code abre el navegador, almacena la autenticación y renueva tokens cuando corresponde. Desde el menú puedes limpiar la autenticación. Algunos proveedores requieren un cliente OAuth registrado y un puerto de retorno fijo:

claude mcp add --transport http \
  --client-id CLIENTE_PUBLICO \
  --client-secret \
  --callback-port 8080 \
  --scope local \
  internal https://mcp.example.com/mcp

--client-secret solicita el valor de forma protegida; evita colocarlo literalmente en el comando, el historial o el repositorio. Para stdio, entrega secretos al proceso mediante variables de entorno o un almacén de credenciales, con alcance mínimo y rotación definida.

16.7 Permisos granulares para herramientas MCP

Las herramientas siguen la forma mcp__servidor__herramienta. Puedes permitir un servidor completo, una operación concreta o forzar confirmación para escrituras. Los nombres reales dependen del servidor y se inspeccionan desde /mcp; los siguientes son ilustrativos:

{
  "permissions": {
    "allow": [
      "mcp__support__get_ticket",
      "mcp__support__search_runbooks"
    ],
    "ask": [
      "mcp__support__add_comment",
      "mcp__support__change_status"
    ],
    "deny": [
      "mcp__support__delete_ticket",
      "mcp__production_db"
    ]
  }
}

mcp__support o mcp__support__* coincide con todas las herramientas de ese servidor en reglas de permisos. Comienza enumerando operaciones de lectura; no uses el comodín en allow solo para eliminar diálogos. Una nueva herramienta publicada en el futuro quedaría incluida automáticamente.

Dos niveles distintos de control

Nivel	Pregunta	Control
Servidor	¿Puede conectarse este endpoint o ejecutable?	Aprobación de proyecto, allowedMcpServers, deniedMcpServers o configuración administrada.
Herramienta	¿Puede invocarse esta operación concreta?	permissions.allow, ask y deny.

16.8 Recursos y prompts provistos por MCP

Cuando un servidor expone recursos, escribe @ y selecciónalos junto con los archivos. Claude Code obtiene el contenido y lo adjunta al mensaje:

Analiza @support:ticket://INC-4821 y compáralo con
@runbooks:file://payments/timeout-recovery.

Indica hechos confirmados, diferencias y datos faltantes.

Los prompts publicados por un servidor aparecen en el menú / como /servidor:prompt. También pueden invocarse con el nombre técnico:

/support:incident-summary INC-4821

/mcp__support__incident_summary INC-4821

Un recurso introduce datos en contexto; una herramienta ejecuta una operación; un prompt introduce una plantilla. En todos los casos trata el contenido remoto como no confiable: puede estar desactualizado o contener instrucciones que no deben prevalecer sobre las reglas del proyecto.

16.9 Tool Search, contexto y límites de salida

Un servidor grande puede ofrecer decenas de esquemas. Tool Search difiere sus definiciones y carga bajo demanda solo las herramientas relevantes; está habilitado por defecto en configuraciones y modelos compatibles. Los nombres siguen visibles para permitir el descubrimiento.

# Carga directa hasta ocupar 5% del contexto y luego difiere
ENABLE_TOOL_SEARCH=auto:5 claude

# Cargar todas las herramientas desde el inicio
ENABLE_TOOL_SEARCH=false claude

También puede configurarse desde env en settings.json. Reserva alwaysLoad: true para servidores pequeños imprescindibles en cada turno, porque sus esquemas ocupan contexto y obligan a esperar la conexión inicial:

{
  "mcpServers": {
    "core-tools": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "alwaysLoad": true
    }
  }
}

Claude Code advierte cuando una salida MCP supera 10.000 tokens y aplica por defecto un máximo de 25.000 a herramientas que no declaran su propio límite. En vez de aumentarlo inmediatamente, mejora la herramienta con paginación, filtros, resúmenes y campos seleccionables.

16.10 Combinar MCP con una Skill

Crearemos .claude/skills/triage-ticket/SKILL.md. La Skill define un análisis reproducible y preautoriza únicamente dos operaciones de lectura. Sustituye los nombres por los anunciados por tu servidor:

---
name: triage-ticket
description: Diagnostica un ticket de soporte usando evidencia y runbooks
argument-hint: "[ticket-id]"
disable-model-invocation: true
allowed-tools:
  - mcp__support__get_ticket
  - mcp__support__search_runbooks
---

Diagnostica el ticket `$ARGUMENTS` sin modificar sistemas externos.

1. Obtén el ticket con `mcp__support__get_ticket`.
2. Extrae síntoma, impacto, cronología, entorno y evidencia.
3. Busca runbooks solamente con términos derivados del ticket.
4. Separa hechos, inferencias y datos faltantes.
5. Propón comprobaciones de menor a mayor riesgo.

Devuelve: resumen, severidad sugerida, hipótesis priorizadas,
evidencia a recopilar y próximo paso. No publiques comentarios
ni cambies el estado del ticket.

/triage-ticket INC-4821

allowed-tools concede esas herramientas durante el turno que invoca la Skill; no restringe por sí solo el resto. Las reglas globales de deny y ask continúan teniendo precedencia. Para una Skill con efectos externos usa activación exclusiva del usuario, permisos específicos y una confirmación explícita en el procedimiento.

16.11 Caso integrador: diagnóstico y comentario controlado

Separaremos lectura y escritura en dos Skills. /triage-ticket investiga sin efectos. Una segunda Skill, /publish-ticket-note, solo publica un borrador ya revisado:

---
name: publish-ticket-note
description: Publica en un ticket una nota previamente aprobada
argument-hint: "[ticket-id] [archivo-borrador]"
disable-model-invocation: true
allowed-tools:
  - Read
  - mcp__support__get_ticket
---

Publica una nota controlada en el ticket `$0` usando el archivo `$1`.

1. Lee el borrador local y vuelve a consultar el ticket.
2. Comprueba que no incluya secretos, datos personales innecesarios
   ni afirmaciones sin evidencia.
3. Muestra exactamente ticket y texto final.
4. Solicita confirmación explícita del usuario.
5. Solo después solicita `mcp__support__add_comment` una vez;
   la regla global `ask` debe mostrar además el diálogo de permiso.
6. Devuelve el identificador o enlace de la nota creada.

Si falta un argumento, cambió el ticket o no hay confirmación,
detente sin publicar.

Esta separación reduce accidentes y facilita auditoría. La Skill no incluye add_comment en allowed-tools: la confirmación del procedimiento y el diálogo provocado por permissions.ask son controles diferentes. Un permiso para comentar no implica permiso para cerrar, eliminar o reasignar el ticket. Si el servidor no ofrece idempotencia, guarda el identificador de respuesta y evita reintentos ciegos después de un timeout.

16.12 Seguridad, diagnóstico y checklist final

Antes de confiar en una integración MCP

Control	Resultado esperado
Procedencia	Proveedor, paquete, endpoint y responsable están identificados.
Versión	El servidor local no depende ciegamente de una versión flotante.
Credenciales	Secreto fuera del repositorio, mínimo alcance, rotación y revocación disponibles.
Ámbito	Local, proyecto o usuario corresponde a quién realmente lo necesita.
Herramientas	Lecturas permitidas; escrituras preguntadas; operaciones destructivas negadas.
Datos	Entrada, salida, logs, retención y jurisdicción fueron evaluados.
Prompt injection	Contenido remoto se trata como datos, no como autoridad.
Volumen	Paginación y filtros evitan respuestas que saturen el contexto.
Fallo	Timeouts, reintentos e idempotencia no duplican efectos.
Observabilidad	Se puede determinar qué herramienta actuó, con qué destino y resultado.

Ante problemas, ejecuta claude mcp list, inspecciona el servidor con claude mcp get, abre /mcp y revisa autenticación, aprobación y variables. Para stdio confirma que el ejecutable existe y arranca fuera de Claude Code; para HTTP verifica URL, TLS, proxy y OAuth. Usa claude --debug sin compartir registros que contengan secretos.

Consulta la documentación oficial para conectar servidores MCP, crear Skills, configurar permisos y revisar las recomendaciones de seguridad.

Conclusión: MCP amplía el alcance de Claude Code hacia sistemas reales; las Skills hacen que esas capacidades se utilicen con el método del equipo. La integración profesional no termina al lograr una conexión: requiere ámbitos correctos, credenciales mínimas, permisos por herramienta, manejo de fallos y resultados auditables. En el próximo tema nos centraremos en prompts y comunicación efectiva.