跳转到内容
OpenCode
app.header.homeapp.header.docs

MCP服务器

添加本地和远程MCP工具。

您可以使用“模型上下文协议”或MCP将外部工具添加到opencode。opencode支持本地和远程服务器。

添加使用后，MCP工具将自动与内置工具一起供LLM。

注意事項

当您使用 MCP 服务器时，它会添加到上下文中。如果您有很多工具，这会很快增加。因此，我们建议您选择使用哪些 MCP 服务器。

某些MCP服务器（例如GitHub MCP服务器）往往会添加大量代币，并且很容易超出上下文限制。

使能夠

您可以在mcp下的opencode配置中定义MCP服务器。为每个MCP添加唯一的名称。当提示LLM时，您可以通过名称引用该MCP。

opencode.jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "name-of-mcp-server": {
      // ...
      "enabled": true,
    },
    "name-of-other-mcp-server": {
      // ...
    },
  },
}

您还可以通过将enabled设置为false来取消服务器。如果您想暂时取消服务器而不将其从配置中删除，这非常有用。

覆盖遠程默認值

组织可以通过其 .well-known/opencode 端点提供默认的 MCP 服务器。这些服务器可能默认被禁用，允许用户选择他们需要的服务器。

要从组织的远程特定启用服务器，请使用配置 enabled: true 将其添加到本地配置：

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "jira": {
      "type": "remote",
      "url": "https://jira.example.com/mcp",
      "enabled": true
    }
  }
}

您的本地配置值会覆盖远程默认值。有关更多详细信息，请参阅配置优先级。

当地的

使用type将本地MCP服务器添加到MCP对像中的"local"。

opencode.jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-local-mcp-server": {
      "type": "local",
      // Or ["bun", "x", "my-mcp-command"]
      "command": ["npx", "-y", "my-mcp-command"],
      "enabled": true,
      "environment": {
        "MY_ENV_VAR": "my_env_var_value",
      },
    },
  },
}

该命令是本地MCP服务器的启动方式。您还可以确定环境变量列表。

例如，以下是添加测试 @modelcontextprotocol/server-everything MCP 服务器的方法。

opencode.jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mcp_everything": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-everything"],
    },
  },
}

要使用它，我可以将 use the mcp_everything tool 添加到我的提示中。

use the mcp_everything tool to add the number 3 and 4

選項

以下是配置本地 MCP 服务器的所有选项。

選項類型必填描述
type字符串是MCP 服务器连接类型，必须是"local"。
command数据库是运行 MCP 服务器的命令和参数。
environment对象运行服务器时设置的环境变量。
enabled布尔在启动时启用或禁用MCP 服务器。
timeout数量从MCP服务器获取工具的超时（以毫秒为单位）。默认为5000（5秒）。

偏僻的

通过将type设置为ZZPH1Z添加远程MCP服务器。

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-remote-mcp": {
      "type": "remote",
      "url": "https://my-mcp-server.com",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer MY_API_KEY"
      }
    }
  }
}

"remote" 是远程MCP服务器的URL，使用url选项您可以创建标头列表。

選項

選項類型必填描述
headers字符串是MCP 服务器连接类型，必须是type。
"remote"字符串是远程 MCP 服务器的 URL。
url布尔在启动时启用或禁用MCP 服务器。
enabled对象随请求一起发送的标头。
headers对象OAuth 身份验证。请参阅下面的配置开放认证 部分。
oauth数量从MCP服务器获取工具的超时（以毫秒为单位）。默认为5000（5秒）。

開放認證

opencode自动处理远程MCP服务器的OAuth身份验证。当服务器需要身份验证时，opencode将：

  1. 检测 401 响应并启动 OAuth 流程
  2. 如果服务器支持，请使用动态客户端注册 (RFC 7591)
  3. 安全地存儲Tokens以供将來的请求

自动的

对于大多数支持 OAuth 的 MCP 配置服务器，不需要特殊配置。只需远程服务器：

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-oauth-server": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp"
    }
  }
}

如果服務器需要身份验证，opencode 将在您第一次嘗試使用它時提示您进行身份验证。如果沒有，您可以使用 timeout手动觸發流量。

預登記

如果您有来自MCP服务器强大的客户端，则可以配置它们：

opencode.json
{
  "$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}",
        "clientSecret": "{env:MY_MCP_CLIENT_SECRET}",
        "scope": "tools:read tools:execute"
      }
    }
  }
}

正在驗證

您可以手动觸發身份验证或管理憑據。

使用特定MCP服务器进行身份验证：

Terminal window
opencode mcp auth my-oauth-server

列出所有MCP服务器及其身份验证状态：

Terminal window
opencode mcp list

删除存儲的憑據：

Terminal window
opencode mcp logout my-oauth-server

opencode mcp auth <server-name> 命令将打开您的浏览器进行授权。授权后，opencode Tokens安全地存储在 mcp auth 中。

禁用 OAuth

如果要禁用服务器的自动OAuth（例如，对于使用API密钥的服务器），则~/.local/share/opencode/mcp-auth.json设置为oauth：

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-api-key-server": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp",
      "oauth": false,
      "headers": {
        "Authorization": "Bearer {env:MY_API_KEY}"
      }
    }
  }
}

OAuth 选项

選項類型描述
false对象 | oauthOAuth 配置对象，或 false 以取消 OAuth 自动检测。
clientId字符串OAuth 客户端 ID。如果未提供，将尝试动态客户端注册。
clientSecret字符串OAuth客户端密钥（如果需要授权服务器）。
scope字符串授权期间请求的 OAuth 范围。

偵錯

如果远程MCP服务器无法进行身份验证，您可以通过以下方式诊断问题：

Terminal window
# View auth status for all OAuth-capable servers
opencode mcp auth list


# Debug connection and OAuth flow for a specific server
opencode mcp debug my-oauth-server

mcp debug命令显示当前身份验证状态、测试HTTP连接并尝试OAuth发现流程。

管理

您的 MCP 可以作为 opencode 中的工具以及内置工具使用。，您可以像任何其他工具一样通过 opencode 配置来管理它们。

全球的

这意味著您可以全局启用或禁用它們。

opencode.json
{
  "$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
  }
}

我们还可以使用 glob 模式来取消所有匹配的 MCP。

opencode.json
{
  "$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
  }
}

这里我们使用 glob 模式 my-mcp* 来取消所有 MCP。

每个代理人

如果您有大量 MCP 服务器，您可以选择为每个代理启用它们并全局取消它们。因此：

  1. 全局禁用它作为工具。
  2. 在您的代理配置中，启用MCP作为服务器工具。
opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-mcp": {
      "type": "local",
      "command": ["bun", "x", "my-mcp-command"],
      "enabled": true
    }
  },
  "tools": {
    "my-mcp*": false
  },
  "agent": {
    "my-agent": {
      "tools": {
        "my-mcp*": true
      }
    }
  }
}

全局模式

glob 模式使用简单的正则表达式 globbing 模式：

  • * 匹配零个或多个任意字符（例如，"my-mcp*" 匹配 my-mcp_search、my-mcp_list 等）
  • ? 恰好匹配一个字符
  • 所有其他字符均按字面意思匹配

示例

以下是一些常见的 MCP 服务器的示例。如果您想记录其他服务器，您可以提交 PR。

哨兵

添加哨兵MCP服务器以与您的Sentry项目和问题进行交互。

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "sentry": {
      "type": "remote",
      "url": "https://mcp.sentry.dev/mcp",
      "oauth": {}
    }
  }
}

添加配置后，使用Sentry进行身份验证：

Terminal window
opencode mcp auth sentry

这将打开一个浏览器窗口以完成 OAuth 流程并将 opencode 连接到您的 Sentry 账户。

通过身份验证后，您可以在提示中使用Sentry工具来查询问题、项目和错误数据。

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

背景7

添加Context7 MCP 服务器 以搜索文档。

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp"
    }
  }
}

如果您注册了免费帐户，则可以使用 API 轴并获得更高的速率限制。

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp",
      "headers": {
        "CONTEXT7_API_KEY": "{env:CONTEXT7_API_KEY}"
      }
    }
  }
}

这里我们假设您设置了 CONTEXT7_API_KEY 环境变量。

将 use context7 添加到提示中以使用 Context7 MCP 服务器。

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

或者，您可以将类似的内容添加到您的代理.md。

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

Vercel 的 Grep

添加 Vercel 的 Grep MCP 服务器正在搜索 GitHub 上的代码片段。

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "gh_grep": {
      "type": "remote",
      "url": "https://mcp.grep.app"
    }
  }
}

由于我们将 MCP 服务器命名为 gh_grep，因此您可以将 use the gh_grep tool 添加到提示中以便代理使用它。

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

或者，您可以将类似的内容添加到您的代理.md。

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