
Cómo Usar MCP en OpenCode: Guía Completa de Configuración y Servidores
Aprende cómo usar MCP en OpenCode paso a paso. Configura servidores locales y remotos, gestiona credenciales en opencode.json, ejecuta herramientas y soluciona errores.
Cómo Usar MCP en OpenCode: Guía Completa de Configuración y Servidores
El protocolo Model Context Protocol (MCP) se ha consolidado como el estándar universal abierto para conectar asistentes de programación con inteligencia artificial a herramientas externas, bases de datos y servicios en la nube. En lugar de crear integraciones frágiles y propietarias para cada utilidad de desarrollo, MCP define un protocolo cliente-servidor unificado que permite a los modelos de lenguaje consultar y operar sobre sistemas en tiempo real de forma segura.
OpenCode—el popular agente de programación para la terminal desarrollado por Anomaly—incorpora soporte nativo de primer nivel para MCP. A través de su sistema de configuración y comandos de terminal, puedes dotar a OpenCode de herramientas personalizadas que van desde bases de datos locales (SQLite, PostgreSQL) hasta conectores con GitHub y rastreadores de documentación técnica.
En esta guía práctica y exhaustiva aprenderás cómo usar MCP en OpenCode desde cero. Analizaremos su arquitectura técnica, la ubicación de los archivos de configuración, cómo conectar servidores locales y remotos paso a paso, cómo gestionar variables de entorno de forma segura, cómo invocar herramientas en la terminal y cómo resolver los errores de conexión más comunes.

1. ¿Qué es MCP? (Visión Conceptual y Técnica)
De forma simple, imagina el Model Context Protocol (MCP) como el puerto USB-C de la inteligencia artificial.
Antes de la llegada de MCP, si querías que un asistente de código consultara tu base de datos, leyera la documentación interna de tu empresa y creara una incidencia en GitHub, cada herramienta necesitaba un plugin propio o un adaptador específico. Con MCP, los desarrolladores crean un único servidor estandarizado, y cualquier cliente compatible (como OpenCode, Claude Desktop o Cline) puede descubrir y ejecutar sus herramientas de forma automática.
Arquitectura Técnica en OpenCode
En este ecosistema, OpenCode actúa como Host y Cliente MCP. Al iniciar una sesión, OpenCode establece comunicación con los servidores registrados, solicita la lista de herramientas (tools), esquemas y recursos disponibles, y los inyecta en el prompt del sistema del modelo de lenguaje subyacente.
flowchart TD Model["Modelo de IA (Claude / GPT / DeepSeek)"] Runtime["Runtime de OpenCode (Cliente / Host MCP)"] LocalServer["Servidor MCP Local<br>(Ej: SQLite, Sistema Archivos)"] RemoteServer["Servidor MCP Remoto<br>(Ej: Jira, Web Docs)"] LocalData["Disco Local / Base Datos"] CloudData["APIs en la Nube"] Model <-->|"Llamada a Función (Tool Calling)"| Runtime Runtime -->|"Transporte Stdio"| LocalServer Runtime -->|"HTTP / SSE"| RemoteServer LocalServer --> LocalData RemoteServer --> CloudData
- Modelo de IA: El motor cognitivo (como Claude 3.5 Sonnet, GPT-4o o un modelo local como Qwen 2.5 Coder) decide cuándo una instrucción del usuario requiere invocar una herramienta externa.
- OpenCode (Cliente/Host): Recibe la solicitud de la herramienta, valida los permisos de seguridad con el usuario, despacha la llamada, recoge la respuesta y la reincorpora a la conversación.
- Servidor MCP: Un proceso independiente (que corre en tu máquina vía
stdioo en la red vía HTTP) que traduce el mensaje en una operación real (una consulta SQL, una llamada API REST, etc.).
2. ¿Qué Puede Hacer MCP Dentro de OpenCode?
Integrar servidores MCP convierte a OpenCode en un agente mucho más potente y contextual. Algunos casos de uso habituales en el día a día incluyen:
- Inspección de Bases de Datos en Vivo: Consultar bases de datos de desarrollo (SQLite, PostgreSQL, MySQL) para examinar esquemas y verificar claves foráneas sin tener que exportar datos manualmente.
- Consulta de Documentación Actualizada: Conectar servidores web para leer documentación técnica oficial de librerías recientes, evitando las alucinaciones por datos de corte desactualizados.
- Gestión de GitHub y Tareas: Consultar pull requests, revisar comentarios en incidencias y etiquetar bugs sin salir de la sesión de terminal.
- Herramientas Internas Propias: Empaquetar scripts empresariales (despliegues, consultas a microservicios o colas Kafka) en servidores MCP privados que OpenCode puede ejecutar de forma supervisada.
3. Video Tutorial: Fundamentos de la Arquitectura MCP
Para comprender visualmente cómo funciona la comunicación cliente-servidor y el descubrimiento de herramientas mediante JSON-RPC, te recomendamos este video explicativo:
Explicación y guia de como usar mcp en opencode
4. Requisitos Previos
Antes de configurar servidores MCP en OpenCode, asegúrate de contar con los siguientes elementos instalados en tu sistema:
- OpenCode Instalado: Si aún no dispones de la herramienta, instálala mediante su instalador oficial:
# Instalador oficial (macOS / Linux) curl -fsSL https://opencode.ai/install | bash # O mediante npm de forma global npm install -g opencode-ai - Node.js y npx: La mayoría de servidores MCP de la comunidad se ejecutan sobre Node.js. Necesitarás Node.js (versión 18 o superior) y el comando
npxdisponible en elPATHdel sistema. - Python y uv (Opcional): Necesario únicamente si vas a utilizar servidores MCP desarrollados en Python.
5. Comprobar la Versión de OpenCode
El soporte para MCP ha evolucionado rápidamente con nuevas especificaciones. Comprueba qué versión tienes instalada ejecutando:
opencode --version
Si dispones de una versión antigua, actualízala mediante el mismo gestor que utilizaste para instalarla (npm update -g opencode-ai o volviendo a ejecutar el script de instalación).
6. Dónde Almacena OpenCode su Configuración
OpenCode gestiona sus ajustes a través de archivos JSON (o JSON con soporte de comentarios, jsonc). La configuración se divide en dos niveles claramente diferenciados:
Jerarquía de Archivos de Configuración
- Configuración de Proyecto (
<raiz>/opencode.json)- Prioridad máxima: aplica solo a este repo
- Configuración Global (
~/.config/opencode/...)- Prioridad base: aplica a todos tus proyectos
Configuración Global
- En Linux y macOS:
~/.config/opencode/opencode.json - En Windows:
%USERPROFILE%\.config\opencode\opencode.json
Se utiliza para herramientas de propósito general que deseas tener disponibles en cualquier repositorio (como motores de búsqueda web, extractores de texto o notas personales).
Configuración por Proyecto
- Ubicación: Archivo
opencode.jsonen la carpeta raíz de tu repositorio.
Se utiliza para servidores específicos del proyecto (la base de datos SQLite local de la aplicación, variables de entorno propias del entorno de pruebas o utilidades de integración continua).
La configuración de proyecto siempre tiene prioridad sobre la global. Si un servidor se llama igual en ambos archivos, se aplicará la definición local del proyecto.
7. Paso a Paso: Cómo Agregar tu Primer Servidor MCP
Para aprender el proceso de forma práctica, configuraremos el servidor oficial de SQLite MCP (@modelcontextprotocol/server-sqlite), el cual permite a OpenCode leer tablas, consultar esquemas y ejecutar queries en archivos SQLite locales.
Paso 1: Crear una Base de Datos de Prueba
En la carpeta de tu proyecto, crea una base de datos de ejemplo:
sqlite3 dev.db "CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT, email TEXT);"
sqlite3 dev.db "INSERT INTO users (name, email) VALUES ('Carlos', 'carlos@example.com'), ('Elena', 'elena@example.com');"
Paso 2: Registrar el Servidor con la CLI de OpenCode
La forma más directa de registrar un servidor MCP es mediante el comando opencode mcp add:
opencode mcp add sqlite -- npx -y @modelcontextprotocol/server-sqlite ./dev.db
Si deseas que este servidor esté disponible de forma global en cualquier carpeta, añade la bandera --global:
opencode mcp add sqlite --global -- npx -y @modelcontextprotocol/server-sqlite /ruta/absoluta/a/tu/base.db
Paso 3: Verificar el Archivo Generado
Abre tu archivo opencode.json. Verás que OpenCode ha añadido la configuración bajo la clave mcp:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"sqlite": {
"type": "local",
"command": [
"npx",
"-y",
"@modelcontextprotocol/server-sqlite",
"./dev.db"
],
"enabled": true
}
}
}
8. Entendiendo la Configuración Línea por Línea
Desglosemos cada propiedad para que comprendas su función exacta en lugar de limitarte a copiar el código:
"$schema": Especifica el esquema de validación oficial de OpenCode (https://opencode.ai/config.json). Esto activa el autocompletado y detecta errores de sintaxis en editores como VS Code."mcp": Objeto que agrupa todos los servidores registrados."sqlite": El identificador único del servidor. OpenCode usará este nombre como prefijo para las herramientas que exponga (por ejemplo:sqlite_read_query)."type": Tipo de transporte. Usa"local"para procesos que se ejecutan en tu máquina vía consola, o"remote"para servicios web por HTTP/SSE."command": Matriz de cadenas con el ejecutable y sus argumentos para levantar el servidor porstdio."enabled": Booleano (trueofalse). Te permite desactivar un servidor puntualmente sin necesidad de borrar su bloque de configuración.
9. Servidores MCP Locales vs. Remotos en OpenCode
OpenCode admite tanto herramientas locales por consola como servicios remotos a través de la red:
Servidores Locales (type: "local")
Se ejecutan como subprocesos en tu propio sistema operativo y se comunican a través de los canales estándar de entrada y salida (stdio).
- Ventajas: Máxima velocidad, acceso directo al disco y privacidad absoluta.
- Requisitos: Necesitan que los runtimes correspondientes (Node.js, Python, Docker) estén instalados en tu ordenador.
Servidores Remotos (type: "remote")
Se ejecutan en infraestructura externa y se comunican mediante HTTP o Server-Sent Events (SSE). Para profundizar en el funcionamiento de servidores remotos sin estado y balanceo de carga, consulta nuestro artículo sobre Arquitectura MCP Stateless.
Para agregar un servidor remoto mediante la terminal:
opencode mcp add docs --url https://mcp.context7.com/mcp
Esto generará la siguiente estructura en tu opencode.json:
{
"mcp": {
"docs": {
"type": "remote",
"url": "https://mcp.context7.com/mcp",
"enabled": true
}
}
}
Si el servidor remoto requiere autenticación con OAuth, OpenCode gestiona las credenciales directamente:
# Iniciar flujo de autorización OAuth
opencode mcp auth docs
# Cerrar sesión o revocar credenciales
opencode mcp logout docs
Los tokens de acceso se almacenan de forma segura en el directorio de usuario (~/.local/share/opencode/mcp-auth.json).
10. Gestión Segura de Variables de Entorno y Claves de API
Muchos servidores MCP (como los conectores con GitHub, Slack o proveedores de bases de datos) requieren tokens de acceso. Nunca debes escribir contraseñas o tokens en texto plano dentro de un opencode.json que vayas a subir a Git.
OpenCode permite inyectar variables de entorno de tu sistema mediante la sintaxis {env:VARIABLE}:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"github": {
"type": "local",
"command": [
"npx",
"-y",
"@modelcontextprotocol/server-github"
],
"environment": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "{env:GITHUB_TOKEN}"
},
"enabled": true
}
}
}
Reglas de Oro para Manejar Secretos
- Sintaxis Dinámica
{env:VARIABLE}: OpenCode lee la variable del entorno de tu terminal al iniciar. - Usa tu archivo
.envo perfil de shell: Define tus claves en tu~/.bashrc,~/.zshrco un archivo.envque esté añadido obligatoriamente a tu.gitignore. - Evita cadenas literales: Si compartes tu proyecto en repositorios públicos, cualquier token escrito en texto plano quedará expuesto.
11. Configuración Realista con Múltiples Servidores MCP
En proyectos reales es frecuente necesitar varias herramientas simultáneamente. A continuación tienes un ejemplo completo de opencode.json con base de datos local, rastreador web y conector de GitHub con políticas de permisos:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"db-sqlite": {
"type": "local",
"command": ["npx", "-y", "@modelcontextprotocol/server-sqlite", "./data/app.db"],
"enabled": true
},
"web-fetch": {
"type": "local",
"command": ["npx", "-y", "@modelcontextprotocol/server-fetch"],
"enabled": true
},
"github": {
"type": "local",
"command": ["npx", "-y", "@modelcontextprotocol/server-github"],
"environment": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "{env:GITHUB_TOKEN}"
},
"enabled": true
}
},
"permission": {
"db-sqlite_*": "allow",
"github_*": "ask"
}
}
Observa el bloque
"permission". Puedes definir reglas con comodines (*). Al fijar"github_*": "ask", OpenCode te solicitará confirmación manual en pantalla antes de publicar comentarios, crear ramas o alterar datos en GitHub.
12. Cómo Comprobar los Servidores Conectados en OpenCode
Una vez guardada tu configuración, verifica que OpenCode reconoce y carga correctamente los servidores.
Verificación por Terminal
Ejecuta el comando opencode mcp list (o su alias opencode mcp ls):
opencode mcp list
Ejemplo de Respuesta:
Configured MCP Servers:
• db-sqlite [local] CONNECTED (3 tools available)
• web-fetch [local] CONNECTED (1 tool available)
• github [local] CONNECTED (14 tools available)
Si algún servidor falla, verás el estado DISCONNECTED o ERROR. Para inspeccionar el origen del fallo, utiliza:
opencode mcp debug <nombre-del-servidor>
13. Cómo Usar las Herramientas MCP en tus Conversaciones
Una vez conectados los servidores, no necesitas aprender comandos nuevos. Simplemente dialoga con OpenCode en su interfaz de terminal (TUI) y el modelo seleccionará automáticamente la herramienta adecuada según lo que le pidas.
Ejemplos Prácticos de Prompts
- Consultar una Base de Datos Local:
Revisa la tabla de usuarios en nuestra base de datos sqlite y dime cuáles son los últimos registros creados.
- Qué hace OpenCode: Reconoce que la herramienta
sqlite_read_queryes la adecuada, ejecuta la consultaSELECT * FROM users ORDER BY id DESC LIMIT 5;y te presenta los datos en una tabla Markdown limpia.
- Qué hace OpenCode: Reconoce que la herramienta
- Leer Documentación Externa:
Usa la herramienta fetch para leer la documentación en https://raw.githubusercontent.com/ejemplo/lib/main/README.md y explícame cómo configurar la paginación.
- Qué hace OpenCode: Llama a
web-fetch_fetch, procesa el contenido web remoto y te responde basándose en la documentación viva sin alucinaciones.
- Qué hace OpenCode: Llama a
- Auditar una Incidencia en GitHub:
Revisa la issue #15 de nuestro repositorio y resume los pasos para reproducir el error.
- Qué hace OpenCode: Ejecuta la herramienta de GitHub
get_issue, lee el contenido de la incidencia y te extrae los pasos técnicos relevantes.
- Qué hace OpenCode: Ejecuta la herramienta de GitHub
Cómo Reconocer que una Herramienta Está en Uso
En la interfaz de consola de OpenCode, las llamadas a herramientas se indican de forma explícita. Verás un distintivo visual con el nombre de la función invocada (por ejemplo: Calling tool: sqlite_read_query) y los argumentos enviados. Si la herramienta requiere confirmación previa ("ask"), OpenCode detendrá la ejecución hasta que pulses Enter para autorizarla.
14. Selección de Servidores MCP Recomendados para Desarrolladores
Para mantener tu entorno ágil, enfócate en servidores estables y de utilidad inmediata:
| Nombre del Servidor | Paquete Oficial / URL | Utilidad Principal | Complejidad de Configuración |
|---|---|---|---|
| SQLite | @modelcontextprotocol/server-sqlite |
Consultar y examinar bases de datos locales | Baja |
| Fetch | @modelcontextprotocol/server-fetch |
Descargar páginas web y convertirlas en Markdown | Baja |
| GitHub | @modelcontextprotocol/server-github |
Gestión de issues, commits y ramas en repositorios | Media (Requiere Token) |
| PostgreSQL | @modelcontextprotocol/server-postgres |
Inspección de esquemas relacionales complejos | Media (Requiere URI de conexión) |
| Filesystem | @modelcontextprotocol/server-filesystem |
Acceso seguro a carpetas aisladas fuera del workspace | Baja |
Para explorar otras alternativas de agentes y herramientas libres, revisa nuestra comparativa de las Mejores Herramientas Open Source de IA para Programar.
15. Consideraciones de Seguridad y Protección de Herramientas
Darle a un agente acceso a la terminal y a bases de datos conlleva responsabilidades operativas. Un servidor MCP mal configurado o expuesto a inyecciones indirectas de prompts podría modificar registros o acceder a datos confidenciales si no se aplican filtros estrictos.
Medidas de seguridad recomendadas:
- Audita Repositorios Desconocidos: Nunca ejecutes
opencodeen un repositorio clonado de internet sin revisar previamente suopencode.json. Dado que OpenCode ejecuta el comando definido encommand, un atacante podría colocar un script malicioso en la configuración. - Aplica Permisos de Confirmación: Asigna siempre
"permission": { "...": "ask" }a cualquier servidor que pueda alterar datos (escrituras en bases de datos, borrado de archivos o peticiones HTTP destructivas). - Controla el Consumo de Contexto: Cada herramienta inyecta descripciones en el prompt del sistema. Habilitar demasiados servidores a la vez puede saturar miles de tokens antes de escribir tu primer mensaje.
- Guía de Seguridad: Para un análisis a fondo sobre mitigación de inyecciones y aislamiento de herramientas, consulta nuestro informe de Hardening y Seguridad en Herramientas de Agentes.
16. Solución de Errores Frecuentes (Troubleshooting)
1. El Servidor Aparece como “DISCONNECTED” en opencode mcp list
- Causa Posible: El comando falló al iniciarse o el binario de Node/Python no está en el
PATH. - Solución: Prueba a ejecutar el comando manualmente en tu terminal (ej:
npx -y @modelcontextprotocol/server-sqlite ./dev.db). Asegúrate de quenpxfunciona correctamente de forma aislada.
2. Error “command not found: npx”
- Causa Posible: OpenCode se inició en un subshell que no carga los gestores de versiones de Node (como
nvm,fnmoasdf). - Solución: Indica la ruta absoluta del binario en tu
opencode.json(por ejemplo:"/usr/local/bin/npx"o"~/.nvm/versions/node/v20.x/bin/npx").
3. Error de Variable de Entorno No Encontrada
- Causa Posible: Usaste
{env:MI_TOKEN}, pero la variable no ha sido exportada en tu sesión activa de terminal. - Solución: Comprueba que la variable existe con
echo $MI_TOKEN. Si está vacía, expórtala conexport MI_TOKEN="tu-clave"antes de iniciar OpenCode.
4. Error de Sintaxis JSON en opencode.json
- Causa Posible: Comas sobrantes al final de listas o barras invertidas no escapadas en rutas de Windows.
- Solución: Cambia la extensión a
opencode.jsoncpara permitir comentarios y asegúrate de que todas las rutas de carpetas utilicen barras inclinadas hacia adelante (/), incluso en sistemas Windows.
17. Cómo Desactivar o Eliminar un Servidor MCP
- Para Desactivarlo Temporalmente: Abre tu
opencode.jsony cambia"enabled": falseen el servidor correspondiente. OpenCode ignorará sus herramientas sin que pierdas tus argumentos de configuración. - Para Eliminarlo Definitivamente: Borra el bloque del servidor dentro de
"mcp"en tuopencode.jsony guarda el archivo. - Para Revocar Credenciales OAuth: Ejecuta
opencode mcp logout <nombre-del-servidor>.
18. Lista de Buenas Prácticas
- Configura herramientas del repositorio en
./opencode.json: Mantén bases de datos y scripts locales vinculados a su proyecto. - Configura utilidades generales en
~/.config/opencode/opencode.json: Mantén herramientas como fetch o documentación accesibles desde cualquier directorio. - Usa siempre
{env:VARIABLE}para contraseñas: Nunca escribas tokens de acceso en texto plano dentro de la configuración. - Revisa periódicamente
opencode mcp list: Desactiva servidores que no estés utilizando para que el modelo responda con mayor velocidad y precisión. - Exige confirmación manual (
"ask") en acciones de escritura: Evita que el agente modifique bases de datos o publique commits sin tu visto bueno.
19. Preguntas Frecuentes (FAQ)
¿Es necesario pagar alguna suscripción para utilizar MCP en OpenCode?
No. Model Context Protocol es un protocolo abierto y completamente gratuito. Sin embargo, si un servidor MCP específico interactúa con una API de pago (como GitHub Enterprise o motores de búsqueda de pago), ese proveedor te cobrará según sus propias tarifas. Si utilizas herramientas locales (como SQLite o el sistema de archivos) junto con modelos abiertos en Ollama, el uso de MCP es 100% gratuito.
¿Puedo usar servidores MCP creados para Claude Desktop en OpenCode?
Sí. Al ser un estándar universal, cualquier servidor desarrollado para Claude Desktop, Cline o Cursor que respete la especificación oficial de MCP funcionará en OpenCode declarándolo en tu opencode.json.
¿Por qué OpenCode no utiliza mis herramientas MCP durante el chat?
Primero, comprueba con opencode mcp list que el servidor figura como CONNECTED. Si está conectado, verifica que el modelo de lenguaje que tienes configurado en OpenCode soporte llamadas a funciones (function calling). Modelos de primera línea como Claude 3.5 Sonnet o GPT-4o ejecutan herramientas de forma nativa, mientras que modelos locales muy pequeños pueden tener dificultades para formatear la llamada técnica correctamente.
¿Puede un servidor MCP modificar archivos fuera de mi proyecto?
Únicamente si ese servidor tiene permisos explícitos sobre el sistema de archivos y fue iniciado con rutas fuera del repositorio. Por ejemplo, el servidor @modelcontextprotocol/server-filesystem solo accede a las carpetas que le pases como argumento al configurarlo. Un servidor SQLite local solo podrá consultar el archivo de base de datos que hayas indicado en su comando.
¿Cuántos servidores MCP puedo tener activos a la vez en OpenCode?
No existe un límite técnico estricto, pero cada servidor añade esquemas y descripciones al contexto inicial del modelo. Activar más de 4 o 5 servidores simultáneamente puede consumir miles de tokens de contexto innecesarios y reducir la precisión del modelo al seguir instrucciones complejas. Lo ideal es mantener activos solo los que necesitas para la tarea actual.
Conclusión
El soporte de Model Context Protocol en OpenCode marca una diferencia cualitativa en el flujo de trabajo de cualquier desarrollador. Dominando la configuración de opencode.json, protegiendo tus credenciales mediante variables de entorno y aprovechando herramientas locales como SQLite o externas como GitHub, transformarás tu terminal en un entorno de desarrollo asistido verdaderamente inteligente, autónomo y seguro.

Yan ZC
Software Developer & Tech Reviewer
Desarrollador de software y analista tecnológico en ToolReview. Pruebo, analizo y documento herramientas de IA y flujos de software. Mi misión es ayudarte a encontrar el stack tecnológico perfecto con reseñas honestas y benchmarks rigurosos.