为 OpenCode 挂载外部能力：MCP 服务器完全指南

OpenCode 通过模型上下文协议（MCP）支持对接本地和远程工具服务。MCP 服务器在配置文件中定义，分为本地（命令行）和远程（HTTP）两种类型，支持 OAuth 认证和自定义请求头。使用时需注意工具调用会占用上下文窗口，建议仅启用必要服务以避免配额耗尽。配置灵活，可覆盖组织默认设置，并提供调试命令排查连接问题。通过精细控制工具启用状态，实现高效集成外部功能。

oscar999

617人浏览 · 2026-05-19 22:30:04

oscar999 · 2026-05-19 22:30:04 发布

模型上下文协议（MCP）让 OpenCode 能够对接外部工具，无论是运行在本地的命令行程序，还是部署在远端的 HTTP 服务。一旦接入，这些 MCP 提供的工具就会和内置功能一样，自动出现在大语言模型的可用工具列表中，直接通过对话进行调用。

使用前的必要提醒

每个 MCP 服务器都会占用一部分上下文窗口。如果同时启用大量工具，很容易塞满 token 配额，尤其是一些返回数据量庞大的服务器。一个典型的例子是 GitHub MCP 服务器，它往往会拉入大量信息，稍不留神就可能超出上下文限制。因此，只开启真正需要的 MCP 服务器，是保持会话高效的关键原则。

启用 MCP 服务器

所有 MCP 服务器都在 opencode.json 配置文件的 mcp 字段下定义。每个服务器拥有一个独一无二的名字，后续在提示词中可以直接引用这个名字来调用工具。

{
  "$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。本地配置的优先级会覆盖远程默认设置。

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

添加本地 MCP 服务器

将 type 设为 "local" 即可定义本地服务器。command 字段负责指定启动该服务器的命令和参数，还可通过 environment 对象注入环境变量。

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

一个实际例子是接入官方的测试服务器 @modelcontextprotocol/server-everything：

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

配置完成后，在提示词中写上“使用 mcp_everything 工具把 3 和 4 相加”，模型就会自动调用对应的运算工具。

本地 MCP 配置选项

选项	类型	必填	描述
`type`	string	是	服务器连接类型，必须为 `"local"`。
`command`	array	是	启动 MCP 服务器的命令及参数。
`environment`	object	否	启动服务器时设置的环境变量。
`enabled`	boolean	否	是否在启动时启用该服务器。
`timeout`	number	否	从 MCP 服务器获取工具的等待时间（毫秒），默认 5000（5 秒）。

添加远程 MCP 服务器

将 type 设为 "remote"，并指定 url 即可接入远程 HTTP MCP 服务。同时可以携带自定义请求头，比如用于 API 密钥鉴权的 Authorization 头。

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

远程 MCP 配置选项

选项	类型	必填	描述
`type`	string	是	服务器连接类型，必须为 `"remote"`。
`url`	string	是	远程 MCP 服务器的 URL。
`enabled`	boolean	否	是否在启动时启用该服务器。
`headers`	object	否	请求时附加的自定义 HTTP 头。
`oauth`	object 或 false	否	OAuth 认证配置，详见下文。设为 `false` 可关闭自动 OAuth。
`timeout`	number	否	从 MCP 服务器获取工具的等待时间（毫秒），默认 5000（5 秒）。

OAuth 认证

远程 MCP 服务器如果需要授权，OpenCode 会自动处理 OAuth 流程。当服务端返回 401 状态码时，会触发以下动作：

尝试使用动态客户端注册（RFC 7591，若服务器支持）
安全存储令牌供后续请求使用

自动模式

绝大多数支持 OAuth 的 MCP 服务器无需额外配置，直接填写 URL 即可。若服务器要求授权，第一次尝试使用时会弹出认证提示；也可以手动执行 opencode mcp auth <服务器名> 来启动流程。

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

预注册客户端凭证

如果已经从服务方拿到了客户端 ID 和密钥，可以直接写入配置：

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

凭证管理命令

手动管理认证状态可以使用以下终端命令：

对指定服务器发起认证：opencode mcp auth my-oauth-server
列出所有 MCP 服务器及认证状态：opencode mcp list
移除已存储的凭证：opencode mcp logout my-oauth-server

执行 mcp auth 命令会打开系统浏览器进行授权，完成后令牌会安全存储在 ~/.local/share/opencode/mcp-auth.json 中。

关闭自动 OAuth

对于使用 API 密钥而非 OAuth 的服务器，可将 oauth 设为 false 来禁用自动认证检测，同时仍可通过 headers 传递密钥：

{
  "$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 选项细节

选项	类型	描述
`oauth`	object 或 false	OAuth 配置对象，设为 `false` 则禁用自动 OAuth 检测。
`clientId`	string	OAuth 客户端 ID。不提供时会尝试动态注册。
`clientSecret`	string	OAuth 客户端密钥，视授权服务器要求而定。
`scope`	string	授权时请求的作用域。

调试连接问题

当远程 MCP 服务器认证失败时，可以使用调试命令定位问题：

# 查看所有具备 OAuth 能力的服务器认证状态
opencode mcp auth list

# 调试特定服务器的连接和 OAuth 流程
opencode mcp debug my-oauth-server

mcp debug 命令会显示当前认证状态、测试 HTTP 连通性，并尝试执行 OAuth 发现流程。

精细控制 MCP 工具

接入的 MCP 服务器会以工具形式出现在 OpenCode 中，与内置工具并列。可以在 tools 字段中像控制其他工具一样管理它们。

全局启用/禁用

直接对 MCP 服务器名进行全局开关设定：

{
  "$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 通配符批量禁用所有匹配的服务器工具。例如，下面这条配置禁用了所有以 my-mcp 开头的 MCP 服务器：

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

按代理（agent）启用

当 MCP 服务器数量较多时，更推荐的做法是全局禁用，只让特定的代理启用。首先在全局工具中将其关闭，然后在目标代理的配置里重新打开：

{
  "$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 模式

OpenCode 的 glob 支持简单规则：

* 匹配零个或多个任意字符（如 my-mcp* 能匹配 my-mcp_search、my-mcp_list 等）
? 匹配恰好一个字符
其他字符原样匹配

有一点需要特别留意：MCP 服务器注册工具时，工具名会带上服务器名称作为前缀。所以，要禁用某个服务器的全部工具，只需使用 "服务器名_*": false 即可。

常见 MCP 服务器示例

以下是一些常用服务器的具体配置，开发者也可以向文档仓库提交 PR 来补充更多案例。

Sentry

接入 Sentry MCP 服务器后，可以直接在对话中查询项目和问题数据。

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

配置好之后，运行 opencode mcp auth sentry 完成浏览器中的 OAuth 授权。接下来就能在提示词里使用 use sentry 要求模型获取最新未解决的 issue 等信息。

Context7

Context7 提供文档搜索能力，适合在需要查阅最新技术资料时调用。

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

如果已经注册了 Context7 的免费账户，还可以提供 API 密钥来获得更高的速率限额。下面的写法假设环境变量 CONTEXT7_API_KEY 已经设置好：

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

使用时在提示词中加入 use context7 即可，也可以在 AGENTS.md 中写入类似指令，让模型自动在需要时搜索文档。

Vercel 的 Grep

Grep 工具能够搜索 GitHub 上的公开代码片段，适合查找实际用例。

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

由于这里给它取名 gh_grep，提示词中可以使用 use the gh_grep tool 来让模型调用。类似的，也可以在 AGENTS.md 里指示模型在不熟悉某个用法时主动使用 gh_grep 搜索 GitHub 代码示例。

通过 MCP 机制，OpenCode 将外部工具与语言模型的交互变得极其顺畅。从本地脚本到需要 OAuth 授权的远程服务，只需一份简洁的 JSON 配置，所有工具就能像内置功能一样被大模型理解和调用。配合灵活的启用策略和 glob 控制，即使在多代理、多工具的复杂环境下，依然能够保持上下文的高效利用。

openEuler 社区

openEuler 是由开放原子开源基金会孵化的全场景开源操作系统项目，面向数字基础设施四大核心场景（服务器、云计算、边缘计算、嵌入式），全面支持 ARM、x86、RISC-V、loongArch、PowerPC、SW-64 等多样性计算架构

更多推荐

伦理量子：AI价值对齐的中式解法

openEuler 社区

Linux文件管理使用详解

第一组表示，如果我的名片上的用户身份证明我是该文件的拥有者，那么我就可以对该文件有读取(r)，写入(w)该文件的权限，但不拥有执行(-，如果拥有执行权限，则为x)该文件的权限。第二组表示，如果我的名片上的组身份证明我所在的组是该文件的拥有组的一员，那么我有从该文件读入的权限。当文件出现在一个目录文件中时，我们就把文件接入到文件系统中，我们称建立一个到文件的硬链接(hard link)。除了这些之外