Ubicación de mcp.json en VS Code: configuración de servidores MCP y registro, paso a paso

Añades un servidor MCP a VS Code, recargas la ventana, abres Copilot Chat y las nuevas herramientas no aparecen por ninguna parte. La mayoría de las veces el servidor funciona bien y el problema está en el archivo: está en la carpeta equivocada, usa la propiedad de nivel superior incorrecta o VS Code está leyendo una copia distinta de la que acabas de editar. Este artículo aclara la ubicación de mcp.json en VS Code para cada configuración, muestra la estructura JSON que espera el editor y explica cómo encaja el registro MCP para que puedas añadir servidores sin copiar comandos de cualquier README.

El Model Context Protocol (MCP) es el estándar abierto que permite a un asistente de IA llamar a herramientas externas: leer una carpeta, consultar una base de datos, abrir una pull request. VS Code actúa como cliente MCP, y cada servidor que activas aparece como un conjunto de herramientas en el modo agente. Toda la configuración vive en un único archivo JSON pequeño, y por eso una ruta mal escrita o un nombre de propiedad incorrecto fallan sin hacer ruido.

Dónde vive mcp.json

VS Code lee las definiciones de servidores MCP desde dos lugares principales, además de un formato portable que se describe más adelante. Piénsalos como una estantería compartida y una estantería personal.

Archivo del espacio de trabajo: .vscode/mcp.json

El archivo del espacio de trabajo está dentro de la carpeta del proyecto, en .vscode/mcp.json. Crea la carpeta .vscode si no existe, coloca el archivo ahí y VS Code lo detectará. Como viaja con el repositorio, cualquiera que clone el proyecto obtiene la misma lista de servidores.

También puedes abrirlo desde la paleta de comandos (Ctrl+Shift+P en Windows y Linux, Cmd+Shift+P en macOS) con MCP: Open Workspace Folder Configuration, o crear una entrada con MCP: Add Server y elegir la opción del espacio de trabajo.

Archivo de usuario según el sistema operativo

El archivo de usuario se aplica a todas las ventanas que abras. La forma más rápida de llegar a él es el comando de la paleta MCP: Open User Configuration, que abre la copia que pertenece a tu perfil activo. En una instalación estándar, el archivo está en la carpeta de datos de usuario de VS Code:

💡 Consejo: VS Code Insiders tiene su propia carpeta de datos, normalmente llamada Code - Insiders en lugar de Code. Si al editar no cambia nada, comprueba que no estás editando la copia estable mientras ejecutas Insiders. En caso de duda, fíate del comando de la paleta más que de cualquier ruta que escribieras de memoria.

Cuál elegir

La elección depende de quién necesita el servidor y de si lleva un token personal.

Evita definir el mismo nombre de servidor en ambos archivos. Con dos copias ya no puedes saber cuál se está ejecutando de verdad, y un informe de error que diga "el servidor está roto" se convierte en una tarde de conjeturas.

Escribir bien el formato del archivo

El archivo tiene hasta tres secciones de nivel superior: servers (obligatoria, un mapa de nombres de servidor a su configuración), inputs (opcional, solicitudes de valores que no quieres guardar) y sandbox (opcional, reglas de archivos y red en macOS y Linux). Todo lo demás depende de estas tres.

Un servidor stdio mínimo

Un servidor stdio es un programa que VS Code inicia en tu equipo y con el que se comunica a través de la entrada y salida estándar. La mayoría de los servidores de la comunidad funcionan así, normalmente con npx o uvx.

{
  "servers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "${workspaceFolder}"]
    }
  }
}

Copiar prompt

La variable ${workspaceFolder} se expande hasta el proyecto abierto, así que el mismo archivo funciona en el equipo de cada compañero. Puedes añadir cwd para el directorio de trabajo, env para las variables de entorno y envFile para cargar variables desde un archivo.

Un servidor HTTP remoto

Un servidor remoto se ejecuta en otro lugar y VS Code se conecta a su URL. Sin proceso local, sin npx, sin problemas de versión de Node.

{
  "servers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    }
  }
}

Copiar prompt

Usa "type": "http" para los servidores remotos actuales y "type": "sse" para los servidores que todavía usan el transporte antiguo de eventos enviados por el servidor. Las entradas remotas también pueden incluir headers para la autenticación y un objeto oauth cuando el servidor admite el inicio de sesión desde el navegador.

La trampa de servers frente a mcpServers

Este es el motivo más habitual por el que una configuración copiada no hace nada.

Por qué tu servidor nunca aparece

La mayoría de los README muestran un fragmento escrito para Claude Desktop, Claude Code o Cursor. Esos clientes usan una propiedad de nivel superior llamada mcpServers. El mcp.json propio de VS Code espera servers. Si pegas la forma incorrecta en .vscode/mcp.json, el archivo puede fallar sin avisar: el editor puede marcar la propiedad, pero la advertencia es fácil de pasar por alto, y no aparece ninguna herramienta.

{
  "mcpServers": {
    "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "."] }
  }
}

Copiar prompt

Ese bloque pertenece a otro cliente. En VS Code, cambia el nombre de la propiedad de nivel superior a servers y añade "type": "stdio" para que la entrada coincida con el formato que se mostró antes.

VS Code también documenta un formato portable: un archivo .mcp.json en la raíz del proyecto, o ~/.copilot/mcp-config.json para el usuario. Esos archivos portables sí usan mcpServers. La regla es sencilla: servers dentro de mcp.json de VS Code, mcpServers en los archivos portables.

Nombres de propiedad por cliente

Repasa esta lista corta cada vez que falten herramientas:

• Revisa el nombre de la propiedad primero. servers para mcp.json, mcpServers para los archivos portables.
• Revisa el type. Un programa local necesita stdio, una URL necesita http o sse.
• Revisa el archivo que abriste. Ejecuta MCP: List Servers y confirma que tu servidor aparece ahí.
• Recarga la ventana tras una edición grande si la lista de servidores parece desactualizada.

Mantén los secretos fuera del archivo

Un mcp.json del espacio de trabajo suele acabar en Git. Todo lo que escribas en él, incluido un token, también acabará ahí.

Pedir tokens con inputs

La sección inputs define valores que VS Code pide en lugar de guardarlos. Haz referencia a uno en cualquier parte de una entrada de servidor con ${input:id}.

{
  "inputs": [
    {
      "type": "promptString",
      "id": "api-token",
      "description": "API token for the image service",
      "password": true
    }
  ],
  "servers": {
    "image-service": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "headers": { "Authorization": "Bearer ${input:api-token}" }
    }
  }
}

Copiar prompt

La URL de arriba es un marcador de posición. Lo que importa es el patrón: promptString con password: true muestra un campo enmascarado, VS Code pide el valor cuando arranca el servidor y el token nunca tiene que estar en el archivo. Existen otros dos tipos de input: pickString para una lista fija de opciones y command para un valor que se obtiene al ejecutar un comando.

💡 Consejo: El mismo patrón sirve para cualquier servicio REST que use un token Bearer, incluida la API para desarrolladores de Picasso IA en api.picassoia.com/v1, cuyos tokens empiezan por pia_sk_. Guarda ese token en un input o en una variable de entorno, nunca en un archivo versionado en Git.

envFile y confianza del espacio de trabajo

En los servidores stdio, envFile carga variables desde un archivo como ${workspaceFolder}/.env. Añade ese archivo a .gitignore antes del primer commit, no después.

La confianza funciona en dos capas. Los servidores definidos en el espacio de trabajo heredan Workspace Trust, así que una carpeta no confiable no los inicia. Los servidores definidos fuera del espacio de trabajo muestran su propio aviso de confianza la primera vez que se ejecutan. El ajuste chat.mcp.autostart controla los reinicios cuando cambia una configuración, con los valores never, onlyNew y newAndOutdated (el predeterminado).

Buscar servidores en el registro

Escribir cada entrada a mano se vuelve pesado muy rápido. VS Code te ofrece dos maneras de evitarlo.

Explorar con @mcp en Extensiones

Abre la vista de Extensiones (Ctrl+Shift+X) y escribe @mcp en el cuadro de búsqueda. La lista que aparece es la galería de servidores MCP dentro del editor. Elige uno, decide si instalarlo en tu perfil de usuario o en el espacio de trabajo, y VS Code añade la entrada al mcp.json correspondiente. Después, abre el archivo y lee lo que se escribió. Es una buena forma de ver la sintaxis correcta de los servidores que añadas a mano más adelante.

Lo que aporta el registro oficial

El official MCP Registry es el directorio público donde los autores de servidores publican sus servidores. Cada entrada indica el paquete o la URL remota, que es exactamente lo que de otro modo pegarías tú mismo en mcp.json. Úsalo cuando un servidor no esté en la galería de Extensiones, y comprueba el nombre del paquete con la entrada del registro antes de ejecutar nada. Un error tipográfico en un argumento npx puede instalar otro paquete.

Detectar servidores automáticamente desde otras aplicaciones

VS Code también puede importar servidores que ya configuraste en otras herramientas. Abre Ajustes, busca chat.mcp y localiza el ajuste que controla la detección automática desde otras aplicaciones. Si quieres empezar desde cero, desactívalo. Si vienes de Claude Desktop, dejarlo activado te ahorra volver a escribir la configuración.

Arreglar un servidor que no arranca

Cuando un servidor muestra un error, la respuesta casi siempre está en su propio registro.

Leer el registro de salida

Ejecuta MCP: List Servers, selecciona el servidor y abre su salida. También puedes abrir mcp.json y mirar encima del nombre del servidor, donde VS Code muestra acciones en línea para iniciar, detener, reiniciar y mostrar la salida. El registro imprime el comando exacto que ejecutó VS Code y lo que el proceso escribió en el error estándar. Lee el primer error, no el último.

Patrones de fallo habituales

Modo desarrollo y sandbox

Si creas servidores, el objeto dev de una entrada stdio resulta útil. watch acepta un patrón glob y reinicia el servidor cuando cambian los archivos que coinciden, y debug conecta un depurador (Node.js y Python son compatibles con los servidores stdio). En macOS y Linux, el objeto sandbox restringe lo que un servidor puede tocar: filesystem.allowWrite, filesystem.denyRead, filesystem.denyWrite, network.allowedDomains y network.deniedDomains. Define sandboxEnabled en un servidor concreto para aplicarlo. Empieza con restricciones estrictas y abre solo lo que el servidor demuestre que necesita.

Redactar tu configuración con Claude Sonnet 5

Si un modelo de lenguaje va a ayudarte con el JSON, que sea uno creado para programar. Claude Sonnet 5 en Picasso IA escribe y depura código, lee capturas de pantalla y te deja elegir cuánto razona. Este es el flujo de trabajo que funciona para mcp.json.

1. Abre la página del modelo. Ve a Claude Sonnet 5 en Picasso IA.
2. Rellena el System Prompt una vez. Algo como: You write VS Code mcp.json files. Use the servers property, never mcpServers. Always set type. Output JSON only.
3. Describe la configuración en Prompt. Indica los servidores que quieres, el sistema operativo y si cada uno debe ser stdio o remoto.
4. Ajusta effort. Déjalo en low para una corrección de una línea. Usa medium o high cuando el archivo combine varios servidores y inputs. El ajuste low desactiva el razonamiento, así que es el más rápido y el más barato.
5. Deja Max Tokens en el valor predeterminado de 8192. Un archivo de configuración necesita mucho menos.
6. Adjunta una captura si tienes un error. El campo opcional Image acepta una, y Max Image Resolution viene por defecto en 0,5 megapíxeles para mantener bajo el costo.
7. Ejecútalo y verifica. Pega el resultado en mcp.json, compara cada nombre de paquete y cada URL con la entrada del registro y observa el registro de salida en el primer arranque.

Un prompt que da un primer borrador útil:

Create a VS Code mcp.json for Windows with two servers: a stdio filesystem
server limited to the workspace folder, and a remote HTTP server at
https://mcp.example.com/mcp that needs a Bearer token. Ask for the token
with an input so it is never stored in the file.

Copiar prompt

💡 Consejo: Los modelos pueden inventar nombres de paquete que suenan bien pero no existen. Trata cualquier matriz args generada como un borrador hasta que la hayas comparado con el registro.

Otros modelos de chat y de programación de la plataforma hacen el mismo trabajo, así que prueba varios y quédate con el que siga mejor tu system prompt:

Crea tus propias imágenes con Picasso IA

Una configuración MCP en funcionamiento merece una documentación que la gente lea de verdad. Un README con una imagen principal clara, un diagrama que muestre cómo se conectan tus servidores o una miniatura de tutorial hacen que una página de configuración parezca terminada. Picasso IA puede generar todo eso.

Empieza con Picasso IA Image para un primer borrador rápido, prueba GPT Image 2 cuando tu imagen necesite texto legible y usa Picasso IA Image Editor Pro para ajustar una imagen que ya tengas. Para escenas fotorrealistas, Seedream 4.5 merece una prueba. La plataforma también incluye texto a video y otros generadores, y puedes ver todas las opciones en la página de todos los modelos.

Escribe un prompt, genera algunas variaciones, elige la que encaje con tu página y colócala en tu documentación. La mejor forma de saber qué funciona en tu proyecto es probarlo, así que abre Picasso IA, escribe una escena que quieras ver y crea tu primera imagen hoy.