Servidor MCP en Cursor: configurar mcp.json paso a paso (2026)

Para usar un servidor MCP en Cursor basta con añadir una entrada a un archivo mcp.json: el del proyecto (.cursor/mcp.json) o el global (~/.cursor/mcp.json). En esta guía vas a ver dónde va cada uno y cómo se escribe la entrada de un servidor local (stdio) y la de uno remoto (url y headers). También verás cómo funciona OAuth, dónde se activan las tools y dónde se leen los registros cuando algo falla.

Los bloques de configuración están copiados literalmente de la documentación de Cursor, de la guía de un proveedor o de la lección 12 del curso, y llevan su fuente al pie. Consultamos esas fuentes el 7 de octubre de 2026. Como ejemplo propio usamos nortia-soporte, de Nortia Logística, la empresa ficticia del curso. Si aún no tienes un servidor, créalo en TypeScript o en Python.

¿Dónde se configura un servidor MCP en Cursor: en el proyecto o global?

Cursor lee dos archivos con el mismo formato:

• Proyecto: .cursor/mcp.json dentro del repositorio, para las tools de ese proyecto. La página de ayuda de Cursor recomienda versionarlo: «Commit this to git so teammates get the same tools».
• Global: ~/.cursor/mcp.json en tu carpeta de usuario, para las tools que quieres en todos los proyectos.

No tienes que elegir uno: «Both files are merged. If the same server name appears in both, the project-level config takes priority». Si declaras nortia-soporte en los dos, gana la entrada del proyecto. Un reparto razonable es poner en el del proyecto los servidores que necesita todo el equipo y que no llevan secretos. En el global van los personales y los que usan una credencial tuya.

También puedes instalar en un clic desde Customize > MCPs (Cursor Marketplace, «Add to Cursor»). La CLI de Cursor también usa estos archivos: «will automatically detect and respect your mcp.json configuration file».

¿Cómo se escribe la entrada de un servidor local (stdio)?

Un servidor stdio es un proceso que Cursor arranca en tu equipo. La entrada lleva el comando, sus argumentos y sus variables de entorno:

{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "mcp-server"],
      "env": {
        "API_KEY": "value"
      }
    }
  }
}

Fuente: https://cursor.com/docs/mcp (ejemplo de stdio).

Los campos de stdio son type ("stdio"), command (obligatorio), args, env y envFile, que solo existe en stdio. La tabla marca type como obligatorio, pero los ejemplos de la misma página lo omiten. Si añades "type": "stdio", la entrada coincide con la tabla.

La tabla de campos no incluye ninguno para el directorio de trabajo: usa rutas absolutas en args o la variable ${workspaceFolder} (siguiente sección).

¿Y la de un servidor remoto por HTTP?

Un servidor remoto se declara con url. Las cabeceras fijas, si el servidor las pide, van en headers:

{
  "mcpServers": {
    "server-name": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "API_KEY": "value"
      }
    }
  }
}

Fuente: https://cursor.com/docs/mcp (ejemplo de servidor remoto; vale para Streamable HTTP y SSE).

Para nortia-soporte, servido por Streamable HTTP en https://mcp.nortia.example/soporte/mcp, la lección 12 del curso usa la forma mínima:

{
  "mcpServers": {
    "nortia-soporte": {
      "url": "https://mcp.nortia.example/soporte/mcp"
    }
  }
}

Fuente: lección 12 del curso, MCP sin programar, pestaña «Cursor (.cursor/mcp.json)».

No lleva token porque nortia-soporte se protege con OAuth y cada persona entra con su propia identidad. Por eso la entrada se puede versionar sin miedo.

Cuando un servidor pide un token fijo, no lo escribas en el archivo. Cursor interpola variables en command, args, env, url, headers y auth. Las que admite son ${env:NAME}, ${userHome}, ${workspaceFolder}, ${workspaceFolderBasename} y ${pathSeparator} (o ${/}). Este es el ejemplo de su documentación para una cabecera:

"Authorization": "Bearer ${env:MY_SERVICE_TOKEN}"

Fuente: https://cursor.com/docs/mcp (interpolación de variables).

Un caso real de token en cabecera es el servidor oficial de GitHub. Su guía para Cursor dice que «While Cursor supports OAuth for some MCP servers, the GitHub server currently requires a Personal Access Token», y propone esta entrada en ~/.cursor/mcp.json:

"github": { "url": "https://api.githubcopilot.com/mcp/", "headers": { "Authorization": "Bearer YOUR_GITHUB_PAT" } }

Fuente: https://github.com/github/github-mcp-server/blob/main/docs/installation-guides/install-cursor.md (entrada que va dentro de mcpServers).

La guía la pone en el archivo global, no en el del proyecto: un PAT en un archivo que se sube al repositorio equivale a publicarlo. Con ${env:…} lo sacas también del archivo global.

¿Cómo funciona OAuth con un servidor MCP en Cursor?

La documentación de Cursor marca la autenticación de SSE y Streamable HTTP como «OAuth» y la de stdio como «Manual». Si el remoto implementa OAuth, basta con la url. Notion lo describe así: añades "notion": { "url": "https://mcp.notion.com/mcp" } a .cursor/mcp.json y después «Open Customize in Cursor’s sidebar, then enable Notion and complete the OAuth flow».

Si el proveedor te da un Client ID fijo, te obliga a registrar la URL de redirección o no admite el registro dinámico de clientes (DCR), usa el objeto auth:

{
  "mcpServers": {
    "oauth-server": {
      "url": "https://api.example.com/mcp",
      "auth": {
        "CLIENT_ID": "your-oauth-client-id",
        "CLIENT_SECRET": "your-client-secret",
        "scopes": ["read", "write"]
      }
    }
  }
}

Fuente: https://cursor.com/docs/mcp (OAuth estático).

Las URL de redirección que tienes que dar de alta en el servidor de autorización son fijas. Para la web y Cursor Agents es https://www.cursor.com/agents/mcp/oauth/callback, y para la aplicación de escritorio, http://localhost:8787/callback. Si omites scopes, Cursor descubre scopes_supported en /.well-known/oauth-authorization-server.

Ten en cuenta que en la especificación 2026-07-28 el registro dinámico de clientes está deprecado (la alternativa son los Client ID Metadata Documents). Si necesitas CLIENT_SECRET, trátalo como cualquier token: con ${env:…} y fuera del repositorio.

¿Dónde se activan las tools y quién aprueba cada llamada?

Una vez cargado el servidor, el agente de Cursor «automatically uses MCP tools listed under Available Tools when relevant». También puedes pedirle una tool por su nombre.

• Servidores: se activan y desactivan desde Customize en la barra lateral. Uno desactivado no se carga ni aparece en el chat.
• Tools sueltas: según la ayuda, «Toggle tools on or off by clicking the tool name in the tools list at the top of the chat panel».
• Aprobación: «Cursor asks for approval before using MCP tools by default». Sin ninguna tool en la lista de permitidas, todo pasa por aprobación o por el clasificador. Desde Cursor 3.6, el modo por defecto es Auto-review (Cursor Settings > Agents > Approvals & Execution): ejecuta al momento las tools que están en la lista de permitidas y pasa el resto por un clasificador. El modo Allowlist conserva el comportamiento anterior.
• Empresas: los administradores definen una lista de permitidos en Team Settings > MCP Configuration (por patrón de comando o de URL, más listas de tools).

Cursor admite tools, prompts, resources, roots, elicitation y la extensión Apps (las interfaces de MCP Apps). Si no conoces alguno de estos términos, lo tienes en el glosario de MCP.

¿Cómo compruebo que el servidor MCP funciona en Cursor?

Cuatro comprobaciones, de la más rápida a la más detallada:

1. Guarda y reinicia. La ayuda de Cursor es explícita tras editar mcp.json: «Save the file and restart Cursor».
2. Mira la lista de tools en la parte superior del panel del chat. Si el servidor está activo en Customize y sus tools no aparecen, algo ha fallado al cargarlo.
3. Lee los registros. Abre el panel Output con Cmd+Shift+U (Ctrl+Shift+U en Windows y Linux) y elige MCP Logs. Según la documentación, «The logs show server initialization, tool calls, and error messages».
4. Desde la CLI, el comando de sesión /mcp [list|list-tools] [identifier] lista los servidores y las tools de uno concreto.

Para probar un servidor tuyo, arráncalo en local y apunta a él con la forma remota. El del tutorial de TypeScript escucha en http://127.0.0.1:3000/mcp cuando lo lanzas por HTTP. Pon esa entrada en el archivo global, no en el del proyecto, para no versionar una URL local. Después pide algo que obligue a usar una tool y comprueba en MCP Logs que la llamada llegó.

Si un servidor falla, Cursor muestra el error en el chat y los demás servidores siguen funcionando.

¿Cuáles son los errores típicos al configurar un servidor MCP en Cursor?

• Variables que Cursor no ve. Si el servidor depende de variables definidas en el perfil de tu shell, la documentación pide asegurarse de que Cursor tiene acceso a ellas y reiniciarlo.
• Un servidor npm que no se actualiza. La documentación indica quitarlo en Customize, ejecutar npm cache clean --force y volver a añadirlo.
• Seguir una guía con menús antiguos. Varias guías de proveedores, entre ellas las de GitHub y Playwright, todavía hablan de «Tools & Integrations > MCP tools» o «Cursor Settings > MCP > Add new MCP Server». La documentación actual usa Customize.
• El campo type. Además de la incoherencia de stdio, la documentación no dice si una entrada remota acepta "type": "http", aunque algunos proveedores (Cloudflare, Supabase) lo ponen en su JSON genérico. Lo documentado para un remoto es url.
• El supuesto límite de 40 tools. El aviso «Exceeding total tools limit» (40 tools) solo aparece en el foro de Cursor y en webs de terceros. La documentación actual no menciona ningún límite, así que no sabemos si sigue vigente. Lo que sí documenta es que desactivar servidores sirve para «reducing tool clutter». El resultado de tools/list llega al modelo aunque no use ninguna tool.

¿En qué se diferencia el mcp.json de Cursor del de Claude Code y VS Code?

El protocolo no dice cómo se le indica a un cliente dónde está el servidor. Cada cliente tiene su formato, y las diferencias rompen la conexión sin un error claro.

Cliente	Archivo	Diferencia con Cursor
Cursor	.cursor/mcp.json o ~/.cursor/mcp.json	Basta url. Admite stdio, SSE y Streamable HTTP
Claude Code	.mcp.json o ~/.claude.json (o claude mcp add)	type es obligatorio: una entrada con url y sin type se interpreta como stdio y se omite. La entrada lleva "type": "http"
VS Code (GitHub Copilot)	.mcp.json en la raíz o .vscode/mcp.json	El archivo propio de VS Code usa servers como objeto raíz, no mcpServers

Fuente: lección 12 del curso (tabla de clientes, comprobada el 2 de octubre de 2026).

La trampa más habitual es la de Claude Code: copias a su .mcp.json la entrada que funciona en Cursor, Claude Code no muestra ninguna tool y nada indica por qué. El cliente ni siquiera llega a enviar una petición al servidor. Si tu equipo usa los dos, escribe la entrada con type en el archivo de Claude Code.

¿Es seguro instalar servidores MCP de terceros en Cursor?

La guía Local Server Security del proyecto MCP lo resume así: «treat a third-party local server as untrusted code with exactly the privileges you hand it — and hand it as few as possible».

Cursor recomienda «Verify the source», «Review permissions», «Limit API keys» y «Audit code». Para datos sensibles añade «Run sensitive servers locally with stdio transport» y «Consider running servers in isolated environments».

Esto choca a primera vista con el proyecto MCP, que dice «Prefer the remote version where one exists». No se contradicen del todo: Cursor habla de no sacar datos sensibles de tu máquina, y MCP de no ejecutar código ajeno sin necesidad. Un servidor que solo envuelve una API remota no gana nada ejecutándose en tu equipo.

Criterios concretos de las guías oficiales:

• Mira el comando completo antes de aprobar. Para la instalación en un clic, la guía Security Best Practices exige que el cliente muestre «the exact command that will be executed, without truncation».
• Comprueba la procedencia y el nombre exacto del paquete (typosquatting), y fija la versión en lugar de latest. Casi todas las guías de proveedores usan @latest.
• Las definiciones de tools son entrada no fiable. Hay riesgo de tool poisoning, de tool shadowing (una tool que interfiere con las de otro servidor) y de rug pull (definiciones que cambian después de que las apruebes). Lee la lista de tools y ten pocos servidores, porque todos comparten el contexto.
• No te fíes de las anotaciones. La especificación dice que los clientes «MUST consider tool annotations to be untrusted unless they come from trusted servers». Un readOnlyHint: true de un servidor desconocido no prueba nada.
• Mantén a una persona en el bucle. Según la especificación, «there SHOULD always be a human in the loop with the ability to deny tool invocations».
• Una credencial por servidor, con el alcance mínimo y fuera de la configuración en texto plano.

Los avisos de seguridad reales de los últimos meses, con sus versiones corregidas, están en seguridad en servidores MCP.

¿Qué versión del protocolo MCP habla Cursor?

No consta. Ni la documentación de MCP de Cursor ni su página de ayuda nombran la revisión del protocolo que usa, y una búsqueda en su changelog no dio resultados. El 7 de octubre de 2026, el único cliente de los que cubre el curso cuya documentación declara soporte de la especificación 2026-07-28 es Claude Code.

Que admita SSE y roots tampoco lo aclara: en la especificación 2026-07-28 los dos figuran como deprecados (HTTP+SSE desde 2025-03-26, Roots desde esta revisión), pero siguen funcionando durante su ventana de retirada.

Según la lección 12, esto tiene una consecuencia: la versión no va en la entrada del servidor, sino que la declara el cliente en cada petición. Un servidor que quiera llegar a todos atiende desde el mismo endpoint la versión actual y las versiones con handshake, y se prueba cliente a cliente. Lo que cambia entre unas y otras lo tienes en MCP 2026-07-28: el protocolo pasa a ser sin estado.

Siguientes pasos

• La lección 12 del curso conecta el mismo servidor a Claude Code, Cursor, Gemini CLI, Codex y los conectores de Claude. Es gratuita con una cuenta.
• Para un servidor propio, los tutoriales de TypeScript y Python (lecciones 09 y 10).
• Los términos, en el glosario de MCP.

Para los clientes de Anthropic tienes conectar un servidor MCP a Claude, y si una tool no aparece, cómo depurar un servidor MCP.