Config MCP de OpenCode: añade servidores, OAuth y soluciones para los timeouts

Añades un servidor MCP a opencode.json, reinicias la terminal y las herramientas nunca aparecen. O aparecen, se abre el inicio de sesión en el navegador y la devolución de llamada nunca llega. O todo funciona hasta que la primera llamada lenta muere por un timeout. Esos tres fallos explican la mayoría de los problemas de config MCP de OpenCode, y cada uno tiene una solución corta y sencilla.

Este artículo repasa los campos exactos que lee OpenCode, los comandos que te dicen qué pasa y los ajustes que acaban con las conjeturas. Los fragmentos siguen la documentación oficial de MCP de OpenCode tal como estaba revisada en octubre de 2026, así que pégalos tal cual y cambia solo los nombres, las rutas y las URL.

Dónde lee OpenCode su configuración

OpenCode no elige un único archivo de configuración e ignora el resto. Combina todas las fuentes que encuentra, y cuando dos fuentes definen el mismo campo, gana la que está más abajo en el orden siguiente. Por eso un servidor que "eliminaste" del archivo del proyecto sigue reapareciendo: sigue definido en tu archivo global.

Ubicaciones de la configuración y orden de combinación

Funcionan tanto JSON como JSONC (JSON con comentarios). Añadir "$schema": "https://opencode.ai/config.json" al principio le da a tu editor autocompletado y subrayados rojos en los errores tipográficos. Los errores tipográficos son la razón más habitual por la que un servidor se ignora en silencio, así que esa línea de esquema se amortiza en cuestión de minutos.

💡 Consejo: Cuando un servidor se comporte de forma extraña, revisa primero el archivo global. Una entrada obsoleta allí puede anular una entrada perfectamente buena del proyecto.

Usa variables, no secretos pegados

OpenCode sustituye dos marcadores en cualquier parte de la configuración. {env:NAME} lee una variable de entorno, y {file:path} inserta el contenido de un archivo. Úsalos para cada token, así la configuración puede subirse a un repositorio sin riesgo.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "tracker": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer {env:TRACKER_TOKEN}"
      }
    }
  }
}

Copiar prompt

Las rutas de archivo relativas se resuelven desde el directorio de configuración, mientras que las rutas que empiezan por / o ~ son absolutas. Si la variable falta en el shell que lanzó OpenCode, el servidor nunca recibe un token válido y responde 401, lo que parece exactamente un token incorrecto. Exporta la variable en el mismo shell y luego inicia OpenCode desde él.

Añade servidores locales y remotos

Todo vive bajo un campo de nivel superior llamado mcp. Cada elemento hijo es un servidor con un nombre que eliges, y ese nombre se convierte en el prefijo de sus herramientas, así que elige nombres cortos, en minúsculas y sin espacios.

Un servidor local mínimo

Un servidor local es un proceso que OpenCode inicia por ti y con el que se comunica mediante la entrada y salida estándar.

{
  "mcp": {
    "files": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/home/dev/projects"],
      "enabled": true,
      "timeout": 15000
    }
  }
}

Copiar prompt

Hay dos campos obligatorios: "type": "local" y command. Lo que confunde a la gente es que command es un array de cadenas, una entrada por argumento, y no una única cadena de shell. Escribir "command": "npx -y some-server" es la forma más rápida de conseguir un servidor que nunca arranca.

Variables de entorno y directorio de trabajo

Los servidores locales a menudo necesitan credenciales o una carpeta concreta. environment pasa variables al proceso hijo, y cwd define su directorio de trabajo. Las rutas relativas en cwd se resuelven desde el espacio de trabajo.

{
  "mcp": {
    "reports": {
      "type": "local",
      "command": ["node", "./tools/reports-server.js"],
      "cwd": "./mcp",
      "environment": {
        "API_TOKEN": "{env:REPORTS_API_TOKEN}",
        "LOG_LEVEL": "info"
      }
    }
  }
}

Copiar prompt

Un servidor remoto con cabeceras

Un servidor remoto ya está en marcha en otro lugar, así que OpenCode solo necesita una dirección y, normalmente, una credencial.

{
  "mcp": {
    "docs": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer {env:DOCS_MCP_TOKEN}"
      },
      "oauth": false,
      "timeout": 20000
    }
  }
}

Copiar prompt

Definir "oauth": false es lo correcto para cualquier servidor que autentique con un token estático. Sin ello, OpenCode trata un 401 como una señal para iniciar un inicio de sesión OAuth, lo que confunde cuando el problema real es un token incorrecto.

Comprueba el resultado con mcp list

Ejecuta opencode mcp list después de cada cambio. Muestra cada servidor configurado y su estado, así sabes en dos segundos si un servidor se conectó, necesita autenticación o falló. Hazlo antes de abrir una sesión y preguntarte por qué faltan las herramientas.

Aquí tienes la referencia completa de campos en un solo lugar:

💡 Consejo: Define "enabled": false en los servidores que solo necesitas de vez en cuando. La entrada se queda en el archivo, y no se carga nada en tu sesión hasta que la vuelvas a activar.

Arregla los problemas de inicio de sesión OAuth

Los servidores remotos que siguen el flujo de autorización de MCP casi no necesitan configuración. Cuando OpenCode recibe un 401, inicia OAuth por sí mismo, se registra como cliente mediante registro dinámico de clientes (RFC 7591), abre tu navegador y espera la redirección. Los tokens resultantes se guardan en ~/.local/share/opencode/mcp-auth.json.

Cómo funciona el OAuth automático

Para un servidor que lo admite, toda la configuración son dos campos y un comando.

1. Añade el servidor solo con type y url.
2. Ejecuta opencode mcp auth tracker, reemplazando tracker por el nombre de tu servidor.
3. Aprueba la solicitud en la pestaña del navegador que se abre.
4. Ejecuta opencode mcp list y confirma que el servidor aparece como conectado.

Cuatro comandos cubren todo el ciclo de vida:

Cuando un inicio de sesión que funcionaba la semana pasada de repente falla, la causa suele ser un token obsoleto o revocado. Ejecuta opencode mcp logout <name> y luego opencode mcp auth <name> de nuevo, y empezarás desde cero.

Clientes preregistrados y scopes

Algunos proveedores no aceptan el registro dinámico y quieren que registres una aplicación a mano. En ese caso, dale a OpenCode los datos del cliente que, de otro modo, habría creado por sí mismo.

{
  "mcp": {
    "tracker": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp",
      "oauth": {
        "clientId": "{env:TRACKER_CLIENT_ID}",
        "clientSecret": "{env:TRACKER_CLIENT_SECRET}",
        "scope": "tools:read tools:execute"
      }
    }
  }
}

Copiar prompt

El valor de scope es una única cadena con los scopes separados por espacios, exactamente como los documenta el proveedor. Pide el conjunto más pequeño que funcione. Un scope demasiado amplio que el proveedor rechaza produce un error en la página de inicio de sesión que no dice nada útil sobre cuál scope es el problema.

El inicio de sesión falla en una máquina remota

Este es el que consume una tarde entera. OpenCode escucha en un puerto local de devolución de llamada mientras inicias sesión, y los informes de usuarios sitúan el valor por defecto en 19876. Si OpenCode se ejecuta en un host remoto por SSH, tu navegador en el equipo portátil redirige a 127.0.0.1:19876 en el equipo portátil, donde no escucha nada. La aprobación se completa, la devolución de llamada nunca llega y el comando acaba agotando el tiempo.

La solución es un reenvío de puertos desde tu equipo portátil al host remoto:

ssh -o ExitOnForwardFailure=yes -L 127.0.0.1:19876:127.0.0.1:19876 user@remote-host

Copiar prompt

Ejecuta opencode mcp auth <name> dentro de esa sesión SSH, abre en tu navegador local la URL que se muestra, y la devolución de llamada ahora viaja por el túnel.

Las compilaciones recientes también aceptan callbackPort y redirectUri dentro del objeto oauth, para proveedores que exigen una devolución de llamada fija y preregistrada. La URI de redirección debe usar http:// con localhost, 127.0.0.1 o [::1] y un puerto explícito. Si cambias el puerto, reenvía ese mismo puerto. Consulta el esquema en tu editor antes de depender de cualquiera de los dos campos, ya que las versiones anteriores no los conocen.

Soluciones de timeout que funcionan

Hay dos timeouts distintos, y confundirlos te hace perder horas. Uno decide cuánto espera OpenCode a que un servidor arranque y liste sus herramientas. El otro decide cuánto puede durar una sola llamada a una herramienta una vez que el servidor está en marcha.

El valor por defecto del arranque

El campo timeout está en milisegundos y su valor por defecto es 5000 tanto para servidores locales como remotos. Cinco segundos bastan para un script pequeño. No bastan para npx -y con una caché fría, porque el paquete tiene que descargarse antes de que el servidor arranque siquiera. Entonces el servidor aparece como fallido y sus herramientas nunca se cargan.

Arréglalo en este orden:

1. Sube el campo solo para ese servidor. Define "timeout": 15000 o 30000 en la entrada lenta y deja las demás como están.
2. Elimina la descarga. Instala el paquete globalmente con npm install -g y luego apunta command al binario instalado. El arranque baja a una fracción de segundo.
3. Prueba el endpoint en los servidores remotos. Ejecuta un curl sencillo contra la URL. Si curl también va lento, el problema es la latencia de red o el servidor, no tu configuración.

Cuando las llamadas a herramientas mueren a los 60 segundos

Un error distinto aparece más tarde, en mitad de una sesión: MCP error -32001: Request timed out. Es el timeout de solicitud de la biblioteca cliente de MCP, y muchos clientes construidos sobre el SDK de TypeScript usan 60 segundos por defecto. Subir el timeout de arranque no cambia nada para una llamada a una herramienta que ya está en ejecución.

Primero busca en el esquema de tu versión un ajuste por solicitud. Si no hay ninguno, cambia la herramienta en lugar del cliente. Haz que la primera herramienta devuelva un id de tarea de inmediato, y añade una segunda herramienta que informe del estado de esa tarea. El modelo envía la solicitud, recibe un id y vuelve a consultar, que es el mismo patrón de enviar y luego consultar que usan las APIs de generación de imágenes y video por la misma razón.

💡 Consejo: Envía los logs del servidor a stderr, nunca a stdout. Un servidor local comparte stdout con el protocolo, así que un solo console.log perdido puede corromper el handshake y parecer un timeout.

Depura un servidor que no se conecta

Cuando la solución no es evidente, deja de editar la configuración y prueba cada capa por separado.

Ejecuta el servidor a mano

Copia el array command en una terminal y ejecútalo en una sola línea. Un servidor stdio sano arranca y espera en silencio a recibir entrada. Si imprime un error, un módulo que falta o una ruta incorrecta, has encontrado el problema sin tener OpenCode de por medio. Después ejecuta opencode mcp debug <name>, que diagnostica los problemas de conexión y de OAuth de ese único servidor.

En un servidor remoto, curl -i la URL con las mismas cabeceras. Un 401 significa credenciales, un 404 significa que la ruta está mal, y un cuelgue significa que el problema es la red.

Errores habituales y soluciones

Mantén el contexto pequeño por agente

Cada servidor conectado añade las descripciones de sus herramientas al contexto que se envía con cada solicitud. Unos pocos servidores pueden consumir una gran parte de la ventana de contexto antes de que escribas una palabra, y el modelo elige peor la herramienta adecuada cuando tiene cincuenta entre las que escoger. La documentación de OpenCode lo dice claramente: usa los servidores MCP con moderación.

Desactiva a nivel global, activa por agente

Los nombres de las herramientas llevan el nombre del servidor como prefijo, así que un patrón glob puede activar o desactivar un servidor entero de una vez. * equivale a cero o más caracteres y ? equivale exactamente a un carácter.

{
  "tools": {
    "files_*": false,
    "tracker_*": false
  },
  "agent": {
    "builder": {
      "tools": { "files_*": true }
    },
    "planner": {
      "tools": { "tracker_*": true }
    }
  }
}

Copiar prompt

Con esta configuración, el agente builder solo ve las herramientas del sistema de archivos y el agente planner solo ve el tracker. Ninguno paga el costo en tokens de la lista de herramientas del otro servidor.

Cómo usar Claude Sonnet 5

Los errores de configuración son un trabajo tedioso de reconocimiento de patrones: una cadena donde debería haber un array, una variable que no está exportada, un puerto que nadie reenvió. Ahí es donde un modelo de programación se gana su tiempo. Claude Sonnet 5 en PicassoIA lee texto de configuración, salida de errores e incluso capturas de pantalla, así que puedes pegar lo que ves y preguntar qué falla.

1. Abre la página del modelo. Ve a Claude Sonnet 5 en PicassoIA y busca el cuadro de prompt.
2. Pega tu bloque mcp. Sustituye antes cada token y cada secreto por un marcador de posición, y luego añade la salida de opencode mcp debug <name>.
3. Ajusta el esfuerzo. El valor por defecto low omite el razonamiento y responde más rápido. Usa medium o high cuando interactúen varios archivos, por ejemplo una configuración global sobrescrita por una configuración del proyecto.
4. Añade un prompt de sistema una sola vez. Algo como: "Revisas configuraciones MCP de opencode.json. Comprueba type, command, timeout y oauth. Responde solo con el JSON corregido".
5. Adjunta una captura de pantalla si tienes una. La entrada de imágenes lee los errores de la terminal. Sube la resolución máxima de imagen cuando el texto de la captura sea pequeño.
6. Deja max_tokens en 8192. Es el valor por defecto y basta de sobra para unos pocos bloques de configuración.
7. Verifica antes de pegar. Revisa cada campo que sugiera frente a la tabla de arriba y la documentación oficial.

💡 Consejo: Nunca pegues un token real en ningún cuadro de chat. Marcadores como TRACKER_TOKEN le dan al modelo todo lo que necesita.

Crea tus propias imágenes hoy

La configuración es solo la mitad de lo que puede hacer MCP. Cuando un agente de programación puede llamar a herramientas, también puede llamar a generadores de imágenes. PicassoIA expone sus generadores mediante MCP, y la dirección del servidor está en la página de conexiones MCP de tu cuenta. Cualquier servidor que hable HTTP sigue el mismo patrón remoto de este artículo: type, url, una cabecera u OAuth, y un timeout razonable.

Si prefieres saltarte la configuración y simplemente crear imágenes, abre Picasso IA y prueba estos modelos de texto a imagen:

• PicassoIA Image para resultados rápidos y de uso general
• Seedream 5 Pro para escenas detalladas y fotográficas
• GPT Image 2 para prompts con composiciones precisas
• FLUX 2 Pro para texturas nítidas y luz natural

Elige uno, escribe un prompt sobre lo que acabas de configurar y compara cómo interpreta cada modelo ese prompt. Diez minutos de experimentación te enseñan más sobre cómo redactar prompts que una hora de lectura, y cada imagen que generes es un ensayo gratuito para la siguiente.