Cómo conectar un servidor MCP a Claude Code (con Hilbana como ejemplo)
Cómo añadir un servidor MCP a Claude Code: los tres transportes, los tres ámbitos, cómo compartirlo con tu equipo, OAuth y un ejemplo real conectando Hilbana.
Claude Code · MCP · Tutorial

Un servidor MCP es la forma que tiene Claude Code de llegar a una herramienta que no está en tu máquina: un tablero de tareas, una base de datos, una web de documentación. Conectar uno lleva un solo comando, pero tres decisiones determinan cómo se comporta: el transporte, el ámbito y la forma de autenticarse. Esta guía las recorre en ese orden y después usa Hilbana como ejemplo real.
Los comandos y comportamientos de abajo salen de la documentación de Claude Code sobre MCP, leída el 2 de noviembre de 2026. Claude Code cambia deprisa, así que si algo difiere, fíate de claude mcp --help y de la documentación oficial.
1. Elige el transporte
| Transporte | Comando | Cuándo |
|---|---|---|
| HTTP (recomendado) | claude mcp add --transport http <nombre> <url> |
Cualquier servidor remoto |
| stdio | claude mcp add --transport stdio <nombre> -- <comando> [args] |
Un servidor que corre en tu máquina |
| SSE | claude mcp add --transport sse <nombre> <url> |
Solo si el servidor no ofrece otra cosa: la documentación lo marca como obsoleto |
En stdio, el -- separa las opciones de Claude del comando del servidor. Lo que va después se lo lleva el servidor. Las variables de entorno van con --env CLAVE=valor y una cabecera de petición con --header "Nombre: valor".
2. Elige el ámbito
El ámbito decide dónde se guarda la conexión y quién la recibe.
| Ámbito | Dónde se guarda | Se comparte con tu equipo |
|---|---|---|
| local (por defecto) | ~/.claude.json, bajo la ruta del proyecto |
No, solo este proyecto |
| project | .mcp.json en la raíz del proyecto |
Sí, mediante el control de versiones |
| user | ~/.claude.json |
No, pero está en todos tus proyectos |
Se elige con --scope, por ejemplo claude mcp add --transport http servidor-compartido --scope project https://ejemplo.com/mcp.
Si el mismo servidor está definido en varios sitios, Claude Code usa este orden: local, project, user, después los servidores que aportan los plugins y por último los conectores de claude.ai. Gana la primera coincidencia como entrada completa; los campos no se mezclan.
Compartirlo con el equipo
Un servidor de ámbito project vive en un fichero .mcp.json que commiteas:
{
"mcpServers": {
"servidor-compartido": {
"type": "http",
"url": "https://ejemplo.com/mcp"
}
}
}
Por seguridad, Claude Code pide aprobación en una sesión interactiva antes de usar un servidor de ámbito project. Si cambias de idea, claude mcp reset-project-choices borra esas respuestas. No pongas nunca un secreto en .mcp.json: está en tu repositorio.
3. Autentícate
Muchos servidores remotos usan OAuth. El flujo es sencillo: ejecuta /mcp dentro de Claude Code, elige el servidor y sigue los pasos en el navegador. Claude Code guarda los tokens y los renueva por ti. Desde una terminal, claude mcp login <nombre> y claude mcp logout <nombre> hacen lo mismo.
Si el servidor necesita una clave, pásala como cabecera:
claude mcp add --transport http api-segura https://api.ejemplo.com/mcp \
--header "Authorization: Bearer tu-token"
Úsalo para un trabajo de CI o un servidor sin OAuth, y guarda el token en tu configuración local, no en el repo.
4. Compruébalo
claude mcp listenseña tus servidores yclaude mcp get <nombre>enseña uno.- Dentro de Claude Code,
/mcpmuestra el estado de cada servidor y permite autenticarse. claude mcp remove <nombre>lo quita. Quitar un servidor remoto borra sus tokens guardados en local, pero no los revoca: ejecuta antesclaude mcp logout <nombre>si quieres revocarlos.
Un ejemplo real: conectar Hilbana
Hilbana es un tablero de tareas para equipos cuyos agentes de IA cogen tareas, las terminan y conservan lo que aprenden. Expone un servidor MCP, así que todo lo anterior se aplica. Hay dos formas de conectarlo.
MCP simple, con OAuth. Sin clave que copiar:
claude mcp add --transport http hilbana https://app.hilbana.com/mcp
Después ejecuta /mcp en Claude Code y autentica el servidor hilbana en el navegador.
El plugin. Añade memoria persistente con ganchos automáticos, contabilidad de tokens por tarea y comandos /hilbana: sobre el servidor MCP. Necesita Node 18 o superior y una clave de API (formato hil_…) creada en Ajustes → Agentes → API keys (solo administradores) del workspace en el que trabajas:
/plugin marketplace add hilbana/claude-plugin
/plugin install hilbana@hilbana
Reinicia Claude Code, ejecuta /mcp y deberías ver plugin_hilbana_hilbana conectado. El paso a paso completo, con el primer ciclo de trabajo, está en la guía Hilbana + Claude Code y en la documentación del plugin.
Qué vigilar
- Confía primero en el servidor. La documentación de Claude Code advierte de que los servidores que traen contenido externo pueden exponerte a inyección de instrucciones. Conecta solo servidores en los que confíes.
- Las respuestas grandes se cortan. Claude Code avisa cuando la salida de una herramienta supera los 10.000 tokens y la limita a 25.000 por defecto. Se cambia con la variable de entorno
MAX_MCP_OUTPUT_TOKENS. - Servidores lentos.
MCP_TIMEOUTfija el tiempo de arranque yMCP_TOOL_TIMEOUTel que se permite a una llamada. - Errores
401. La clave está incompleta, revocada o caducada. Crea otra y pégala entera: Hilbana la enseña una sola vez. - El trabajo cae en el workspace equivocado. Con una clave de API se usa el workspace de esa clave. Créala en el workspace que quieres.
Puedes probar Hilbana gratis: el plan Free no caduca y no pide tarjeta.
Los comportamientos de Claude Code de este artículo se leyeron en code.claude.com/docs/en/mcp el 2 de noviembre de 2026. Los pasos de Hilbana salen de nuestra propia guía.