Configura MCP en Cursor paso a paso. Descubre dónde están los archivos mcp.json globales y de proyecto, cómo escribir entradas de servidores locales y remotos con variables seguras, cómo funcionan los interruptores y las aprobaciones en Settings, cómo se comportan las instalaciones desde el marketplace y cómo arreglar un servidor que no arranca.
Pegas un fragmento en un archivo de configuración, reinicias el editor y el nuevo servidor aparece con un punto rojo junto a su nombre. Ese momento es la razón por la que una configuración de MCP en Cursor limpia importa. El Model Context Protocol permite que el Agent de Cursor llame a herramientas externas, desde un navegador hasta una base de datos o un generador de imágenes, pero solo cuando la conexión está bien montada. Este artículo sigue el camino en orden. Verás dónde vive mcp.json, cómo escribir entradas locales y remotas, qué interruptores hay en Settings, cómo el Marketplace instala servidores con un solo clic y qué revisar cuando algo falla. Cada configuración de abajo usa los nombres de campo de la propia documentación de Cursor, y ningún secreto se guarda en el archivo.
MCP es un protocolo abierto que ofrece a un cliente de IA una forma estándar de comunicarse con programas externos. Cursor es el cliente. Cada programa que conectas es un servidor, y cada servidor expone herramientas que el Agent puede llamar durante un chat: leer un archivo, consultar una base de datos, abrir una página web, registrar un ticket o generar una imagen.
Piensa en tres capas. El Agent decide qué le pediste. El servidor anuncia lo que puede hacer. Una herramienta es una acción con un nombre, una descripción y un conjunto de entradas. Cuando le pides a Cursor que averigüe por qué un endpoint devuelve un 500, el Agent lee la lista de herramientas, elige las que encajan y te pide permiso antes de ejecutarlas.
De ahí se derivan dos consecuencias prácticas:
github o project-files hacen que las solicitudes de aprobación sean fáciles de leer más tarde.💡 Empieza con uno o dos servidores que vayas a usar a diario. Añade el resto cuando una tarea real los necesite.
Así se ve en el trabajo diario. Un servidor de navegador permite al Agent abrir tu sitio de pruebas, recorrer un proceso de compra y decirte qué se rompió. Un servidor de GitHub le permite leer una incidencia, encontrar el código relacionado y redactar el texto del pull request. Un servidor de base de datos le permite revisar una fila antes de sugerir una migración. En todos los casos, el Agent deja de adivinar y empieza a leer datos reales, que es el motivo completo para dedicar diez minutos a la configuración.
Cursor admite tres transportes, y la elección determina cómo escribes la entrada en mcp.json.
| Transporte | Dónde se ejecuta | Quién lo gestiona | Inicio de sesión |
|---|---|---|---|
| stdio | En tu equipo | Cursor inicia y detiene el proceso | Manual, mediante valores de entorno o encabezados |
| SSE | Local o remoto | Tú o un proveedor lo despliega | OAuth compatible |
| Streamable HTTP | Local o remoto | Tú o un proveedor lo despliega | OAuth compatible |
Un servidor stdio es el más sencillo: Cursor lanza un comando como npx y se comunica con él por entrada y salida estándar. Un servidor remoto es simplemente una URL. Confías en que el proveedor lo ejecute y, a menudo, inicias sesión desde el navegador con OAuth en lugar de pegar un token.
Cursor lee las definiciones de MCP de un archivo JSON llamado mcp.json. Hay dos ubicaciones para él, y puedes usar ambas a la vez.
| Ámbito | Ruta | Ideal para |
|---|---|---|
| Global | ~/.cursor/mcp.json | Herramientas que quieres en todos los espacios de trabajo, como GitHub, un servidor de notas o un generador de imágenes |
| Proyecto | .cursor/mcp.json en la raíz del repositorio | Herramientas ligadas a una base de código concreta, como su base de datos o su API de staging |
En Windows, la carpeta de inicio es tu perfil de usuario, así que el archivo global está en C:\Users\YourName\.cursor\mcp.json.
Cursor combina los dos archivos. Da nombres distintos a los servidores en cada uno para que nunca te preguntes qué definición se está ejecutando. Sube el archivo de proyecto al repositorio solo si no contiene secretos, y usa variables para todo lo privado.
Un archivo de proyecto compartido tiene una ventaja más: un nuevo miembro del equipo clona el repositorio y obtiene la misma lista de servidores sin necesidad de una llamada de configuración. Después, cada persona aporta sus propios tokens mediante variables de entorno, así el archivo es idéntico para todos mientras las credenciales siguen siendo personales.
Cada archivo tiene un objeto superior llamado mcpServers. Dentro, cada nombre de propiedad es la etiqueta de un servidor, y el valor indica cómo llegar a él.
| Campo | Para qué se usa | Ejemplo |
|---|---|---|
command | El programa que Cursor lanza para un servidor stdio | npx |
args | Argumentos que se pasan a ese programa | ["-y", "@playwright/mcp@latest"] |
env | Valores de entorno que se entregan al proceso | {"API_TOKEN": "${env:MY_TOKEN}"} |
envFile | Un archivo dotenv que se carga para el proceso | .env |
url | Dirección de un servidor remoto | https://example.com/mcp |
headers | Encabezados HTTP que se envían a un servidor remoto | {"Authorization": "Bearer ..."} |
Una entrada stdio usa command, args, env y envFile. Una entrada remota usa url y headers. Mantén separadas las dos formas: una entrada, un transporte.
Cuatro pasos resuelven casi todos los casos: crear el archivo, añadir una entrada, guardar y comprobar el resultado en Settings. Los dos ejemplos siguientes muestran una entrada local y una remota.
~/.cursor/mcp.json si todavía no existe.{
"mcpServers": {
"project-files": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "${workspaceFolder}"]
}
}
}
La marca -y permite que npx instale el paquete sin preguntar. La variable ${workspaceFolder} apunta el servidor al proyecto abierto, así que solo accede a archivos dentro de esa carpeta.
Una entrada remota sustituye command y args por una url. Este ejemplo conecta el servidor alojado de GitHub y lee el token desde una variable de entorno.
{
"mcpServers": {
"github": {
"url": "https://api.githubcopilot.com/mcp/",
"headers": {
"Authorization": "Bearer ${env:GITHUB_TOKEN}"
}
}
}
}
Los servidores que admiten OAuth no necesitan ningún encabezado. Cursor abre una ventana del navegador la primera vez que los usas, apruebas el acceso y el inicio de sesión se guarda para sesiones posteriores. Cuando un proveedor te da un ID de cliente y un secreto de cliente fijos, Cursor acepta un objeto auth con CLIENT_ID, CLIENT_SECRET y scopes. Para la aplicación de escritorio, registra http://localhost:8787/callback como dirección de redirección.
Cursor expande estas variables dentro de command, args, env, url y headers:
${env:NAME} lee una variable de entorno.${userHome} es tu directorio personal.${workspaceFolder} es la raíz del proyecto.${workspaceFolderBasename} es el nombre de la carpeta del proyecto.${pathSeparator} o ${/} da la barra correcta para el sistema operativo.Un servidor local que necesita una dirección de base de datos y una ruta de script puede combinarlas:
{
"mcpServers": {
"notes-db": {
"command": "node",
"args": ["${userHome}${/}tools${/}notes-server${/}index.js"],
"env": { "DB_URL": "${env:NOTES_DB_URL}" },
"envFile": "${workspaceFolder}/.env"
}
}
}
💡 Nunca pegues un token real en un archivo que vayas a subir al repositorio. Referencia una variable de entorno y añade
.enva.gitignore.
Abre Cursor Settings y busca Tools & MCP. Las versiones recientes también muestran los mismos servidores en Customize, en la barra lateral. Este es el centro de control de todo lo que escribiste en mcp.json.
Cada servidor tiene un interruptor y un contador de herramientas. Uno sano muestra sus herramientas. Uno con fallos muestra un estado de error. Tres comprobaciones te dicen el estado de un vistazo:
Desactiva los servidores que no necesites para una tarea concreta en lugar de borrarlos. La entrada se mantiene en el archivo y volver a activarla tarda un segundo. Además, es la forma más rápida de reducir la carga de contexto antes de una refactorización larga.
Por defecto, Cursor pide aprobación antes de que se ejecute una herramienta MCP. Ves el nombre de la herramienta y sus argumentos, y luego aceptas o rechazas. Las herramientas MCP siguen las mismas reglas de Run Mode que los comandos de terminal, así que si tu modo ejecuta de inmediato las acciones de la lista de permitidos, las herramientas MCP de la lista también se ejecutan de inmediato.
💡 Permite las herramientas de solo lectura, como búsqueda, listado y obtención de datos. Mantén la aprobación activa para todo lo que escriba, borre, publique o gaste dinero.
Escribir JSON a mano funciona, pero la mayoría empieza por el marketplace. Los listados están en cursor.com/marketplace y en cursor.directory.
Cada listado tiene un botón Add to Cursor. Al pulsarlo se abre Cursor, te pide confirmación y escribe la entrada en tu ~/.cursor/mcp.json global. Si el servidor necesita OAuth, Cursor te lleva después a la página de inicio de sesión del proveedor.
Después, abre la lista de MCP y comprueba el contador de herramientas. La entrada es JSON normal, así que puedes editarla más tarde: renombrarla, añadir un valor env o moverla a un archivo de proyecto.
Un servidor se ejecuta con tus permisos, así que una instalación de un clic merece diez segundos de desconfianza.
npx descarga código de un registro y lo ejecuta en tu equipo.package@version cuando la estabilidad importe más que las actualizaciones.Si no sabes qué añadir primero, esta breve lista se ajusta a las tareas diarias más habituales:
| Tarea | Tipo de servidor | Por qué merece un lugar |
|---|---|---|
| Probar una página web en un navegador real | Automatización de navegador, como Playwright | El Agent ve la página renderizada, no solo el código fuente |
| Trabajar con incidencias y pull requests | Servidor alojado de GitHub | Incidencias, ramas y revisiones quedan en un solo chat |
| Leer y editar archivos fuera del repositorio | Sistema de archivos, limitado a una carpeta | El acceso termina donde tú trazas la línea |
| Revisar datos antes de una migración | Un servidor de base de datos con un usuario de solo lectura | Filas reales, sin riesgo de una escritura errónea |
La mayoría de los fallos vienen de cinco o seis causas. Empieza por los registros y luego compara con el síntoma.
Abre el panel Output con Cmd+Shift+U en Mac o Ctrl+Shift+U en Windows y Linux, y luego elige MCP Logs en el desplegable. El registro guarda la inicialización del servidor, las llamadas a herramientas y los mensajes de error. Lee el primer error, no el último. Las líneas posteriores suelen ser efectos secundarios.
| Síntoma | Causa probable | Solución |
|---|---|---|
| Punto rojo, "command not found" | npx o node no está en el PATH que ve Cursor | Instala Node, reinicia Cursor o indica la ruta absoluta en command |
| Funciona en una terminal, falla en Cursor en Windows | npx es un script, no un ejecutable | Usa "command": "cmd" con "args": ["/c", "npx", "-y", "package"] |
| Configuración ignorada | JSON no válido, como una coma final o un comentario | Valida el archivo, porque JSON no admite ninguno de los dos |
| Arranca y luego da error al iniciar sesión | Una variable está vacía porque Cursor se abrió desde un menú, no desde tu shell | Define el valor en env o envFile y reinicia |
| 401 o 403 desde un servidor remoto | Encabezado incorrecto o un inicio de sesión OAuth caducado | Revisa el valor de Authorization e inicia sesión de nuevo |
| Herramientas que no aparecen en el chat | Servidor desactivado o el chat empezó antes de recargar | Actívalo y abre un chat nuevo en modo Agent |
Cuando ninguna de esas filas encaja, ejecuta el servidor a mano. Copia command y args de tu entrada en una terminal, con los mismos valores de entorno, y observa lo que imprime. Si falla ahí, el problema está en el servidor o en su instalación, no en Cursor. Si funciona bien, compara el PATH y las variables de la terminal con lo que Cursor pasa a través de env, y revisa de nuevo el registro buscando la primera línea que mencione al servidor por su nombre.
La conexión es solo la mitad del trabajo. Tres funciones de PicassoIA ayudan en torno a ella.
Redactar y revisar configuraciones. Un modelo de lenguaje (LLM) puede detectar una coma final, explicar un error de los MCP Logs o convertir un fragmento de instalación de un README en una entrada de Cursor. En PicassoIA puedes usar Claude Sonnet 5, GPT 5.6 Sol, Kimi K2.6 o Gemini 3.5 Flash desde un único lugar y comparar cómo interpreta cada uno el mismo error. Sustituye todos los tokens por marcadores de posición antes de pegar una configuración.
Imágenes para documentación y READMEs. Las páginas de configuración se leen mejor con una imagen de cabecera clara. Seedream 4.5, Flux 2 Pro y GPT Image 2 convierten un prompt de texto en una imagen fotográfica, y la imagen a video puede convertir una imagen fija en un clip corto para un changelog o una publicación en redes.
Una conexión MCP propia. PicassoIA ofrece una API en https://api.picassoia.com/v1 y conexiones MCP gestionadas desde tu cuenta, que abarcan la generación de imágenes, la edición de imágenes y la generación de video con audio. Se ejecutan hasta cinco predicciones a la vez por cuenta, compartidas entre tokens y conexiones MCP, así que una sesión que lance muchas solicitudes se pondrá en cola. La dirección del servidor aparece dentro de tu cuenta, por eso este artículo no la incluye. Una vez que la tengas, la entrada sigue la misma forma url que el ejemplo de github de arriba. Revisa la página de tu plan para confirmar qué niveles incluyen conexiones MCP antes de construir un flujo de trabajo sobre ello.
Elige un servidor de este artículo, añádelo hoy y aprueba tú mismo su primera llamada a una herramienta. Después, abre PicassoIA y genera una imagen de cabecera para tus propias notas de configuración: una foto de tu escritorio, un fondo tranquilo para un diagrama o un clip corto para una publicación de lanzamiento. Prueba tres prompts distintos, compara los resultados y quédate con el que encaje en tu página. La lista completa de modelos está en picassoia.com/en/all-models.
Elige tu idioma
