Configuración del servidor MCP de OpenCode

MCP (Model Context Protocol, Protocolo de Contexto del Modelo) es un protocolo abierto que te permite conectar herramientas y fuentes de datos externas a OpenCode. Después de agregar un servidor MCP, las herramientas que proporciona se muestran automáticamente junto a las herramientas integradas de OpenCode, y el LLM puede llamarlas directamente en la conversación.

OpenCode admite dos tipos de servidores MCP:

  • Local: procesos MCP iniciados mediante línea de comandos en tu máquina, adecuados para herramientas y scripts locales
  • Remoto: servicios MCP remotos conectados a través de HTTPS, adecuados para servicios en la nube y plataformas de terceros

Aviso sobre consumo de contexto:Cada servidor MCP ocupa espacio de contexto en la conversación. Cuantas más herramientas estén habilitadas, más tokens se consumen por conversación y más fácil es alcanzar el límite de contexto del modelo. Se recomienda habilitar solo los servidores MCP que la tarea actual realmente necesite y desactivarlos después de usarlos. Algunos servidores (como GitHub MCP) tienen una gran cantidad de herramientas, y el consumo de tokens es especialmente significativo; ten especial cuidado al usarlos.

Estructura básica de configuración

Toda la configuración del servidor MCP se escribe enopencode.jsondemcpel campo correspondiente. Cada servidor necesita unnombre únicocomo nombre de clave. Este nombre también se puede usar en el prompt para especificar a qué MCP llamar:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-mcp-server": {         // 服务器名称（自定义，全局唯一）
      "type": "local",         // 连接类型：local o  remote
      // ...其他配置项
      "enabled": true          // 是否启用，默认为 true
    },
    "another-mcp-server": {    // 可同时配置多个 MCP 服务器
      "type": "remote",
      // ...
    }
  }
}

va aenabledEstablecer enfalsepuede deshabilitar temporalmente un servidor sin eliminarlo del archivo de configuración, lo que facilita activarlo o desactivarlo según sea necesario:

Ejemplo

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-mcp-server": {
      "type": "local",
      "command": ["npx", "-y", "my-mcp-command"],
      "enabled": false          // Deshabilitado temporalmente, la configuración se conserva; la próxima vez que lo necesites, cámbialo de nuevo a true
    }
  }
}

Servidor MCP local

Un servidor MCP local proporciona herramientas ejecutando un proceso de comando en tu máquina. Establecetypeen"local"y especifica el comando de inicio mediantecommand:

Ejemplo

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-local-mcp-server": {
      "type": "local",                                   // Tipo de conexión: local
      "command": ["npx", "-y", "my-mcp-command"],        // Array del comando de inicio:
                                                         // El primer elemento es el ejecutable,
                                                         // Los elementos siguientes son argumentos
                                                         // También se puede escribir como ["bun", "x", "my-mcp-command"]
      "enabled": true,
      "environment": {                                   // Variables de entorno inyectadas en tiempo de ejecución (opcional)
        "MY_ENV_VAR": "my_env_var_value"
      }
    }
  }
}

Opciones de configuración del servidor local

Opción de configuración Tipo Obligatorio Descripción
type Cadena Sí Tipo de conexión; debe completarse para servidores locales"local"
command Array Sí Comando y argumentos para iniciar el servidor MCP, en forma de array, como["npx", "-y", "my-mcp"]
environment Objeto no Variables de entorno inyectadas al ejecutar el servidor, en forma de pares clave-valor
enabled Booleano no Si se habilita el servidor al inicio, por defectotrue
timeout Número no Tiempo de espera (en milisegundos) para obtener la lista de herramientas del servidor MCP, por defecto5000(5 segundos)

Ejemplo: agregar un servidor MCP de prueba

A continuación se muestra un ejemplo para agregar el servidor MCP de prueba oficial@modelcontextprotocol/server-everything, que puede usarse para verificar si la funcionalidad MCP funciona correctamente:

Ejemplo

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mcp_everything": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-everything"]
      // npx -y confirma automáticamente la instalación; no es necesario ejecutar npm install manualmente
    }
  }
}

Una vez completada la configuración, agrega el nombre del servidor en el prompt para que el LLM pueda llamar a las herramientas de ese MCP:

use the mcp_everything tool to add the number 3 and 4

Servidor MCP remoto

Un servidor MCP remoto se conecta a servicios en la nube a través de HTTPS. Establecetypeen"remote"y especifica la dirección del servidor medianteurl:

Ejemplo

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-remote-mcp": {
      "type": "remote",                               // Tipo de conexión: remoto
      "url": "https://my-mcp-server.com",             // Dirección del servidor remoto (obligatorio)
      "enabled": true,
      "headers": {                                    // Cabeceras HTTP enviadas con cada solicitud (opcional)
        "Authorization": "Bearer MY_API_KEY"          // Se usa comúnmente para autenticación con clave API
      }
    }
  }
}

Opciones de configuración del servidor remoto

Opción de configuración Tipo Obligatorio Descripción
type Cadena Sí Tipo de conexión; debe completarse para servidores remotos"remote"
url Cadena Sí Dirección HTTPS completa del servidor MCP remoto
enabled Booleano no Si se habilita el servidor al inicio, por defectotrue
headers Objeto no Cabeceras HTTP enviadas con cada solicitud, se usan comúnmente para autenticación con clave API
oauth Objeto /false no Configuración de autenticación OAuth, o establecer enfalsepara deshabilitar la detección automática de OAuth
timeout Número no Tiempo de espera (en milisegundos) para obtener la lista de herramientas del servidor MCP, por defecto5000(5 segundos)

Referencia a variables de entorno

En el archivo de configuración,no debes escribir información sensible como claves API directamente en texto plano. OpenCode admite leer variables de entorno del sistema en tiempo de ejecución mediante la sintaxis{env:变量名}:

Ejemplo

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-remote-mcp": {
      "type": "remote",
      "url": "https://my-mcp-server.com",
      "headers": {
        "Authorization": "Bearer {env:MY_API_KEY}"    // Lee automáticamente el valor de la variable de entorno MY_API_KEY en tiempo de ejecución
                                                      // Esta variable de entorno debe configurarse previamente en el sistema:
                                                      // export MY_API_KEY=your_actual_key
      }
    }
  }
}

Autenticación OAuth

OpenCode tiene soporte integrado de autenticación OAuth para servidores MCP remotos. Todo el proceso es casi totalmente automático, sin necesidad de manejar tokens manualmente.

Flujo de autenticación automática

Cuando el servidor requiere autenticación OAuth, OpenCode completa automáticamente los siguientes pasos:

  1. Detecta que el servidor devuelve una respuesta 401 (no autorizado)
  2. Inicia automáticamente el flujo de autorización OAuth y abre el navegador para guiarte en el inicio de sesión
  3. Cuando el servidor lo admite, registra automáticamente la aplicación mediante el registro dinámico de clientes (RFC 7591)
  4. Almacena de forma segura el token obtenido en~/.local/share/opencode/mcp-auth.jsonMedio
  5. Las solicitudes posteriores incluyen automáticamente el token, sin necesidad de iniciar sesión repetidamente

1. OAuth automático (sin configuración adicional)

Para la mayoría de los servidores MCP que admiten OAuth, solo necesitas configurarurl; OpenCode te guiará automáticamente para completar la autenticación en el primer uso:

Ejemplo

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-oauth-server": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp"
      // Sin necesidad de configuración adicional, OpenCode maneja automáticamente el flujo OAuth
    }
  }
}

También puedes activar manualmente el flujo de autenticación (por ejemplo, para volver a iniciar sesión después de que el token expire):

opencode mcp auth my-oauth-server

2. Credenciales de cliente previamente registradas

Si ya has obtenido un ID de cliente y un secreto fijos del proveedor de servicios, puedes especificarlos directamente en la configuración y omitir el paso de registro dinámico:

Ejemplo

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-oauth-server": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp",
      "oauth": {
        "clientId": "{env:MY_MCP_CLIENT_ID}",          // Se lee desde variables de entorno para evitar exponerlo en texto plano
        "clientSecret": "{env:MY_MCP_CLIENT_SECRET}",
        "scope": "tools:read tools:execute"             // El alcance de permisos solicitado; los valores específicos los define el proveedor de servicios
      }
    }
  }
}

3. Deshabilitar OAuth (usar autenticación con clave API)

Si el servidor usa claves API en lugar de autenticación OAuth, puedes estableceroauthenfalsepara deshabilitar la detección automática de OAuth, y usarheaderspara pasar la clave:

Ejemplo

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-api-key-server": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp",
      "oauth": false,                                   // Deshabilita la detección automática de OAuth
      "headers": {
        "Authorization": "Bearer {env:MY_API_KEY}"     // Autenticación directa con clave API
      }
    }
  }
}

Opciones de configuración de OAuth

Elemento de configuración Tipo Descripción
oauth Objeto /false Objeto de configuración de OAuth; establézcalo enfalsepara deshabilitar por completo la detección automática de OAuth
clientId Cadena ID de cliente OAuth. Si no se proporciona, OpenCode intentará el registro dinámico de cliente.
clientSecret Cadena Secreto del cliente OAuth (si el servidor de autorización lo requiere).
scope Cadena Ámbito de permisos solicitados durante la autorización; varios permisos se separan con espacios; los valores específicos los define el proveedor de servicios.

Comandos de gestión de autenticación

OpenCode proporciona un conjunto de herramientas de línea de comandos para gestionar el estado de autenticación de MCP:

# 对指定 MCP 服务器进行身份验证（会打开浏览器完成 OAuth 授权）
opencode mcp auth my-oauth-server

# 列出所有已配置的 MCP 服务器及其当前认证状态
opencode mcp list

# 删除指定服务器已存储的凭据（下次使用时需要重新登录）
opencode mcp logout my-oauth-server

# 调试指定服务器的连接和 OAuth 流程（显示认证状态、测试连接、执行 OAuth 发现流程）
opencode mcp debug my-oauth-server

# 查看所有支持 OAuth 的服务器的认证状态
opencode mcp auth list

Sobrescribir la configuración predeterminada remota

Las organizaciones pueden, mediante el.well-known/opencodeendpoint, proporcionar a los miembros configuraciones de servidores MCP preestablecidas; estos servidores pueden estar deshabilitados de forma predeterminada. Si necesitas habilitar uno de ellos, añade una entrada con el mismo nombre en la configuración local y estableceenabled: truey basta con eso,la configuración local anulará los valores predeterminados remotos.：

Ejemplo

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "jira": {                                         // Coincide con el nombre del servidor en la configuración remota de la organización
      "type": "remote",
      "url": "https://jira.example.com/mcp",
      "enabled": true                                 // En local, configúralo en true para anular el estado deshabilitado predeterminado remoto
    }
  }
}

Gestión de herramientas

Cuando un servidor MCP se registra, sus herramientas aparecen como服务器名称_工具名称en la lista de herramientas de OpenCode, y se pueden gestionar de manera unificada mediante eltoolscampo.

1. Deshabilitar globalmente las herramientas de un MCP específico

Ejemplo

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-mcp-foo": {
      "type": "local",
      "command": ["bun", "x", "my-mcp-command-foo"]
    },
    "my-mcp-bar": {
      "type": "local",
      "command": ["bun", "x", "my-mcp-command-bar"]
    }
  },
  "tools": {
    "my-mcp-foo": false    // Deshabilita todas las herramientas del servidor my-mcp-foo (el servidor seguirá iniciándose, pero las herramientas no estarán disponibles)
  }
}

2. Deshabilitar en lote utilizando patrones Glob

Usando comodines Glob se pueden emparejar y deshabilitar de una sola vez las herramientas de varios servidores MCP:

Ejemplo

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-mcp-foo": {
      "type": "local",
      "command": ["bun", "x", "my-mcp-command-foo"]
    },
    "my-mcp-bar": {
      "type": "local",
      "command": ["bun", "x", "my-mcp-command-bar"]
    }
  },
  "tools": {
    "my-mcp*": false    // Patrón Glob: deshabilita las herramientas de todos los servidores cuyo nombre comience con my-mcp
  }
}

3. Habilitar herramientas MCP específicas por agente

Si has configurado una gran cantidad de servidores MCP, pero cada agente solo necesita una parte de ellos, puedes deshabilitar primero globalmente todas las herramientas MCP y luego habilitarlas según sea necesario en la configuración de un agente específico. Esto permite controlar con precisión a qué herramientas puede acceder cada agente, evitando el desperdicio de contexto:

Ejemplo

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-mcp": {
      "type": "local",
      "command": ["bun", "x", "my-mcp-command"],
      "enabled": true         // El servidor en sí permanece iniciado (de lo contrario, el agente tampoco podría usarlo)
    }
  },
  "tools": {
    "my-mcp*": false          // Paso 1: Deshabilita globalmente todas las herramientas de este MCP; no estarán disponibles en la conversación predeterminada
  },
  "agent": {
    "my-agent": {
      "tools": {
        "my-mcp*": true       // Paso 2: Habilítalas solo en el agente my-agent; otros agentes no se ven afectados
      }
    }
  }
}

Reglas de patrones Glob

Comodín Significado Ejemplo
* Coincide con cero o más caracteres arbitrarios my-mcp*Coincide conmy-mcp_search、my-mcp_listesperar
? Coincide exactamente con un carácter arbitrario my-mcp?Coincide conmy-mcpA, pero no coincide conmy-mcpAB
otros caracteres Coincidencia exacta por valor literal my-mcp-fooSolo coincide con servidores cuyo nombre sea exactamente igual

Las herramientas de un servidor MCP se registran con el nombre del servidor como prefijo; por ejemplo, el servidormyservercuyas herramientas se registran comomyserver_toolnamePor lo tanto, para deshabilitar todas las herramientas de un servidor, utiliza"myserver_*": falsey así se logra la coincidencia exacta.

Ejemplo de configuración

Sentry

Añade el servidor MCP de Sentry y podrás consultar directamente en la conversación los errores, problemas y datos de eventos de los proyectos de Sentry:

Ejemplo

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "sentry": {
      "type": "remote",
      "url": "https://mcp.sentry.dev/mcp",
      "oauth": {}      // Un objeto vacío indica que se habilita la autenticación automática de OAuth; OpenCode manejará automáticamente todo el flujo de OAuth
    }
  }
}

Después de añadir la configuración, ejecuta el siguiente comando para completar la autorización de la cuenta (se abrirá un navegador para el inicio de sesión de OAuth):

opencode mcp auth sentry

Una vez completada la autenticación, añade en el promptuse sentrypara invocar las herramientas de Sentry:

Show me the latest unresolved issues in my project. use sentry

Context7

Añade el servidor MCP de Context7 y podrás buscar varios tipos de documentación técnica en la conversación, ayudando al LLM a obtener referencias de API precisas y actualizadas:

Ejemplo

// Versión básica (sin optimización de límite de tasa)
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp"
    }
  }
}

Ejemplo

// Después de registrar una cuenta gratuita, puedes obtener límites de tasa más altos usando la clave API
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp",
      "headers": {
        "CONTEXT7_API_KEY": "{env:CONTEXT7_API_KEY}"    // Lee la clave API desde la variable de entorno
                                                        // Debe configurarse de antemano: export CONTEXT7_API_KEY=your_key
      }
    }
  }
}

Añade en el promptuse context7para invocar la función de búsqueda de documentación:

Configure a Cloudflare Worker script to cache JSON API responses for five minutes. use context7

También puedes, en el archivo del proyecto,AGENTS.mdañadir reglas globales para que el LLM use Context7 automáticamente cuando necesite consultar documentación, sin tener que especificarlo manualmente cada vez:

When you need to search docs, use `context7` tools.

Grep by Vercel

Añade el servidor MCP de Grep by Vercel y podrás buscar directamente en la conversación fragmentos de código reales en GitHub, ayudando al LLM a encontrar el uso correcto de las API y referencias de implementación:

Ejemplo

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "gh_grep": {           // El servidor se llama gh_grep; en el prompt se hace referencia a él por ese nombre
      "type": "remote",
      "url": "https://mcp.grep.app"
    }
  }
}

Añade en el promptuse the gh_grep toolpara buscar ejemplos de código en GitHub:

What's the right way to set a custom domain in an SST Astro component? use the gh_grep tool

De igual manera, puedes, en el archivo,AGENTS.mdconfigurar reglas globales para que el LLM busque automáticamente ejemplos de código cuando no esté seguro del uso:

If you are unsure how to do something, use `gh_grep` to search code examples from GitHub.
Otras extensiones