Configuración de OpenCode MCP: 7 pasos para servidores locales y remotos

Esta guía responde a una intención distinta: añadir, autenticar, comprobar, limitar y diagnosticar herramientas MCP. La instalación general, Ollama y el almacenamiento de sesiones conservan sus propias páginas para evitar canibalización.

Los ejemplos siguen el esquema y los comandos oficiales actuales. Cada proveedor puede cambiar URL, paquete, permisos o autenticación, por lo que debes confirmar los valores en su documentación oficial y nunca ejecutar paquetes desconocidos en un repositorio sensible.

Un servidor local es un proceso hijo iniciado por OpenCode. Conviene para paquetes CLI confiables o herramientas que necesitan archivos locales. Su estabilidad depende del runtime, gestor de paquetes, directorio, variables de entorno y permisos del sistema.

Un servidor remoto es un endpoint HTTP. Facilita servicios compartidos como documentación, observabilidad o bases de datos, pero depende de red y autenticación. Elige el transporte soportado oficialmente, no el formato que parezca más cómodo.

OpenCode combina las fuentes de configuración. Los valores globales sirven para varios proyectos y opencode.json en la raíz debe reservarse para herramientas del repositorio. Los secretos pertenecen a variables de entorno u OAuth, nunca a Git.

Asigna a cada servidor un nombre estable y descriptivo. Ese nombre aparece en prompts, prefijos de herramientas y reglas por agente. Usa enabled: false para mantener documentado un servidor opcional sin cargarlo siempre.

Una entrada local requiere type: "local" y un array command. Verifica el editor y repositorio del paquete, fija versión cuando importe la estabilidad y prueba primero en un directorio sin datos sensibles.

Pasa tokens con environment y sustituciones de entorno. Empieza con permisos de solo lectura y una cuenta de desarrollo. Una herramienta puede heredar toda la autoridad del token aunque el modelo parezca limitado.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "docs_search": {
      "type": "local",
      "command": ["npx", "-y", "trusted-mcp-package"],
      "enabled": true,
      "environment": { "MCP_TOKEN": "{env:MCP_TOKEN}" }
    }
  }
}

Sustituye el paquete de ejemplo solo por el comando oficial del propietario.

Una entrada remota requiere type: "remote" y HTTPS. Usa headers solo según el proveedor. OpenCode puede iniciar OAuth al recibir 401 y también permite opencode mcp auth <server-name> de forma explícita.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "monitoring": {
      "type": "remote",
      "url": "https://provider.example/mcp",
      "oauth": {}
    }
  }
}

Comprueba el estado con opencode mcp list y diagnostica conexión u OAuth con opencode mcp debug <server-name>. Después ejecuta una consulta de solo lectura y compara el resultado con el sistema de origen.

Registra nombre, paquete o URL, runtime, autenticación, prefijo, prompt de prueba, timeout y rollback. Esa evidencia permite reproducir la integración en otro equipo sin adivinar configuraciones.

1. Confirmar proveedorUsar paquete, endpoint y autenticación oficiales.
2. Elegir alcanceGlobal, proyecto o agente especializado.
3. Añadir una entradaActivar un servidor nuevo cada vez.
4. Proteger credencialesVariables de entorno u OAuth, nunca Git.
5. Listar y depurarComprobar estado, conexión y OAuth.
6. Probar lecturaComparar la consulta con el origen.
7. Conceder escrituraSolo tras revisar logs y rollback.

opencode mcp list
opencode mcp auth <server-name>
opencode mcp debug <server-name>
opencode mcp logout <server-name>

Las descripciones de herramientas consumen contexto. Desactiva servidores amplios que no uses y habilítalos solo para el agente especializado. Compara calidad y uso de tokens antes y después de añadirlos.

Antes de compartir logs o credenciales, consulta la guía de sesiones y privacidad de OpenCode y revisa la guía de OpenCode Ollama si los MCP convivirán con un modelo local de contexto menor.

Diagnostica por capas: proceso o endpoint, autenticación, descubrimiento de OpenCode y finalmente prompt o política. Cambiar varias capas a la vez oculta la causa real y dificulta el rollback.

Para Figma o Supabase, sigue primero la instalación oficial del proveedor y aplica después esta lista común. No copies JSON genérico que ignore permisos, proyecto, región o método de autenticación.

Para la instalación básica, vuelve a la guía de despliegue de OpenCode. La precedencia y opciones oficiales aparecen en las fuentes.