Cómo añadir un servidor MCP a Cursor (con Hilbana como ejemplo)
Cómo configurar servidores MCP en Cursor con mcp.json: servidores remotos y locales, variables de entorno, OAuth y un ejemplo real conectando Hilbana con una clave de API.
Cursor · MCP · Tutorial

En Cursor, un servidor MCP son unas líneas en un fichero JSON. Lo que hace tropezar no es el formato sino lo que lo rodea: dónde va el fichero, cómo sacar una clave de él y qué pasa cuando el servidor usa OAuth. Esta guía cubre eso y después conecta Hilbana como ejemplo real.
Lo que sigue sobre Cursor sale de su documentación de MCP, leída el 2 de noviembre de 2026. Los menús de Cursor cambian a menudo, así que donde la documentación y tu pantalla no coincidan, fíate de la pantalla.
Dónde vive la configuración
Cursor lee los servidores MCP de un fichero llamado mcp.json, en dos sitios posibles:
~/.cursor/mcp.json: herramientas disponibles en todos los proyectos..cursor/mcp.jsonen la raíz de un proyecto: herramientas solo para ese proyecto.
La documentación no dice cuál gana si los dos definen el mismo servidor, así que evita definir un servidor en ambos.
Los dos formatos
Un servidor remoto necesita una URL y, si la pide, cabeceras:
{
"mcpServers": {
"nombre-del-servidor": {
"url": "https://ejemplo.com/mcp",
"headers": { "API_KEY": "valor" }
}
}
}
Un servidor local ejecuta un comando en tu máquina:
{
"mcpServers": {
"nombre-del-servidor": {
"command": "npx",
"args": ["-y", "mcp-server"],
"env": { "API_KEY": "valor" }
}
}
}
Saca los secretos del fichero
Cursor resuelve variables dentro de command, args, env, url y headers. La que más usarás es ${env:NOMBRE}, que lee una variable de entorno. Hay otras, como ${userHome} y ${workspaceFolder}.
Así, en vez de pegar una clave, escribes "Bearer ${env:MI_CLAVE}" y defines MI_CLAVE antes de abrir Cursor. Importa sobre todo en .cursor/mcp.json: está dentro de tu repositorio.
Autenticación
- Clave de API o token: ponlo en
headers(remoto) o enenv(local), con la sintaxis de variables de arriba. - OAuth: los servidores remotos pueden usar el flujo de código de autorización con PKCE. Si el servidor admite registro dinámico de clientes, Cursor se registra solo y tú inicias sesión. Para un servidor que exige una aplicación preregistrada, añades un objeto
authconCLIENT_IDy, opcionalmente,CLIENT_SECRETyscopes. La documentación de Cursor lista las URL de redirección que hay que registrar.
Cuando un token caduca, Cursor lo renueva si el servidor emitió un token de renovación; si no, vuelves a iniciar sesión.
Actívalo y compruébalo
La documentación de Cursor dice que los servidores MCP se gestionan desde Customize, en la barra lateral, donde también puedes activar o desactivar cada uno. Versiones anteriores y muchas guías llaman a ese sitio Settings → Tools & MCP, así que busca el que enseñe tu versión. El servidor debería aparecer activado con su lista de herramientas. Si no, reinicia Cursor.
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. Cursor se conecta a su servidor MCP con una clave de API.
1. Crea la clave. En Hilbana, abre Ajustes → Agentes → API keys (solo administradores) y crea una. Puede ser de solo lectura o limitarse a un proyecto. Empieza por hil_ y se muestra una sola vez.
2. Añade el servidor a ~/.cursor/mcp.json o a .cursor/mcp.json:
{
"mcpServers": {
"hilbana": {
"url": "https://app.hilbana.com/mcp",
"headers": { "Authorization": "Bearer ${env:HILBANA_API_KEY}" }
}
}
}
3. Define la variable HILBANA_API_KEY con tu clave antes de abrir Cursor y reinícialo.
4. Pruébalo. Pídele al agente, en lenguaje normal: «Lista mis proyectos de Hilbana.» Después: «Coge la siguiente issue lista para agente y ponte con ella.» Si te responde con tus proyectos, estás conectado.
Para quitar el acceso, borra la clave en Ajustes → Agentes → API keys: Cursor lo pierde al instante. La misma configuración vale para Codex, y hay una versión para Claude Code de esta guía.
Qué vigilar
- Confía en el servidor. Las notas de seguridad de Cursor dicen que los servidores MCP pueden acceder a servicios externos y ejecutar código en tu nombre. Comprueba de dónde viene un servidor, revisa los permisos que pide y limita las claves que le das.
- Usa la clave más estrecha. Si un agente solo necesita leer, crea una clave de solo lectura; si trabaja en un proyecto, limita la clave a ese proyecto.
- No commitees claves. Prefiere
${env:…}en cualquier fichero que viva en un repositorio.
Puedes probar Hilbana gratis: el plan Free no caduca y no pide tarjeta.
Los comportamientos de Cursor de este artículo se leyeron en cursor.com/docs/context/mcp el 2 de noviembre de 2026. Los pasos de Hilbana salen de nuestra propia documentación.