MCP en OpenCode: servidores remotos en opencode.json

En corto: los servidores MCP de OpenCode se describen en el bloque mcp del archivo opencode.json. Un servidor remoto necesita "type": "remote" y url; para entrar, una clave en headers o opencode mcp auth. Abajo hay una configuración lista y aquello que las guías breves se saltan: cómo no inflar el contexto del agente con herramientas.

Qué le aporta MCP a un agente en la terminal

OpenCode ya sabe leer el proyecto, editar archivos y ejecutar comandos. MCP añade lo que está fuera del repositorio: documentación actual de las librerías sacada de internet, la lectura de la página que describe un error, la generación de iconos e imágenes para la interfaz sobre la marcha. Qué es MCP en general está en el repaso de los servidores MCP.

Paso 1. La clave

Si ya apuntaste OpenCode a nuestra API siguiendo el capítulo «opencode: configurar tu propio proveedor», ya tienes clave: la misma clave abre también los servidores MCP, con saldo común. Si no, consíguela aquí, sin registro:

Guarda la clave en una variable de entorno para que no acabe en git:

export TWELVER_API_KEY="sk-<tu-clave>"

Paso 2. El bloque mcp en opencode.json

La configuración global está en ~/.config/opencode/opencode.json; la del proyecto, en opencode.json en la raíz del repositorio. Añade los servidores:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "twelver-web-search": {
      "type": "remote",
      "url": "https://twelver.app/api/mcp/v1/web-search",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer {env:TWELVER_API_KEY}"
      }
    },
    "twelver-image": {
      "type": "remote",
      "url": "https://twelver.app/api/mcp/v1/image-generation",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer {env:TWELVER_API_KEY}"
      }
    }
  }
}

Reinicia OpenCode y comprueba que los servidores se conectaron:

opencode mcp list

La variante sin clave: OAuth

Si quitas headers, OpenCode verá que el servidor pide acceso y te ofrecerá hacerlo desde el navegador. También se puede lanzar a mano:

opencode mcp auth twelver-web-search

Para entrar por OAuth hace falta una cuenta registrada. Si algo va mal, opencode mcp debug nombre-del-servidor muestra en qué paso se quedó el acceso, y opencode mcp logout borra los tokens guardados.

Paso 3. Compruébalo en una sesión

Pídele al agente algo que requiera una herramienta:

• «Busca en la documentación cómo se configuran las cabeceras de caché en la última versión de Next.js y arregla next.config»: el agente irá a web-search, leerá la página y sólo después tocará el código.
• «Genera un icono de aplicación 1:1 en estilo plano y deja el enlace en el README»: eso es text-to-image.

Cómo no sobrecargar al agente de herramientas

Cada servidor conectado añade las descripciones de sus herramientas a cada petición al modelo. Eso cuesta tokens y, peor aún, dispersa la atención del modelo: con veinte herramientas disponibles acierta menos al elegir. Tres reglas prácticas:

• En la configuración global, sólo lo que hace falta en todas partes: normalmente, la búsqueda. La generación de imágenes, actívala en la configuración del proyecto de frontend.
• Desactiva en vez de borrar: "enabled": false deja el servidor en la configuración pero no lo carga al arrancar.
• Conecta el conjunto que encaje con la tarea. Los servidores de Twelver están separados por conjuntos justamente para esto: la búsqueda aparte, las imágenes aparte, el vídeo aparte.

Modelo y herramientas con una sola clave

Lo que hace que valga la pena montar esta combinación: OpenCode puede tomar de Twelver tanto el modelo (mediante un proveedor compatible con OpenAI) como las herramientas (mediante MCP), con una clave y un saldo. El proveedor se configura en el capítulo «opencode: configurar tu propio proveedor» y MCP como aquí arriba; los dos bloques viven en el mismo opencode.json.

Si no funciona

¿No programas sólo en la terminal? El mismo esquema para Codex y Cursor, y una selección de lo que conviene conectar está en los mejores servidores MCP.