← Volver al blog

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.

Equipo HilbanaProducto

Claude Code · MCP · Tutorial

Cómo conectar un servidor MCP a Claude Code (con Hilbana como ejemplo)

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

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

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.

← Volver al blog