叶云梦天

OpenCode MCP 服务器集成完全指南：让 AI 编程助手接入整个工具生态

引言

在使用 AI 编程助手时，你可能会遇到这样的场景：想查一下 Sentry 上最新的错误日志，需要切换到浏览器打开 Sentry 控制台；想搜索某个开源库的最新文档，得手动打开搜索引擎；想看看 GitHub 上别人是怎么用某个 API 的，又要打开 Grep 搜索。这些上下文切换不仅打断思路，还降低了开发效率。

OpenCode 通过 MCP（Model Context Protocol，模型上下文协议） 彻底解决了这个问题。MCP 是 Anthropic 提出的一种开放协议，它定义了 AI 模型与外部工具之间的标准通信方式。OpenCode 完整支持 MCP，你可以将各种本地或远程的 MCP 服务器接入 OpenCode，让 AI 助手直接调用这些工具——就像调用它内置的 read、write、bash 一样自然。

本文将带你从零开始，掌握在 OpenCode 中配置和使用 MCP 服务器的全部知识，包括本地服务器、远程服务器、OAuth 认证、权限管理以及多个实战案例。

MCP 服务器是什么

简单来说，MCP 服务器就是一个实现了 MCP 协议的服务端程序，它向 AI 模型暴露一组"工具"。LLM 在对话时可以直接"看到"这些工具的描述和参数，并根据需要调用它们。

举个例子，当你接入 Sentry 的 MCP 服务器后，你可以直接对 OpenCode 说：

看看我们项目最近 24 小时有哪些未解决的高优先级错误，用 sentry 工具

OpenCode 就会自动调用 Sentry MCP 服务器，获取错误列表，并用自然语言总结给你。整个过程都在终端内完成，无需离开编辑器。

配置 MCP 服务器

在 OpenCode 中，所有 MCP 服务器的配置都写在 opencode.json（或 opencode.jsonc）文件的 mcp 字段中。每个 MCP 服务器有一个唯一的名字，你可以通过这个名字在提示词中引用它。

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

enabled 字段默认为 true，设为 false 可以临时禁用某个服务器而不删除配置。

本地 MCP 服务器

本地 MCP 服务器是在你本机运行的进程。你只需要指定启动命令，OpenCode 会在后台管理它的生命周期。

基本配置

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

command 是一个数组，第一个元素是可执行文件，后面的元素是参数。环境变量通过 environment 字段传入。

完整配置选项

| 选项 | 类型 | 必填 | 说明 |
|------|------|------|------|
| type | String | 是 | 必须为 "local" |
| command | Array | 是 | 启动命令和参数 |
| cwd | String | 否 | 工作目录，相对路径基于工作区 |
| environment | Object | 否 | 环境变量键值对 |
| enabled | Boolean | 否 | 是否在启动时启用 |
| timeout | Number | 否 | 获取工具的超时时间（毫秒），默认 5000 |

实战：接入 Everything 测试服务器

MCP 官方提供了一个测试用的 server-everything 包，我们来实际接入它：

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

配置完成后，你可以在提示词中这样使用：

使用 mcp_everything 工具计算 3 加 4 的结果

AI 助手会自动识别这个工具并调用它。这种集成方式的妙处在于，LLM 能像理解内置工具一样理解你的自定义工具——它会根据工具的描述和参数签名，自主决定何时调用。

远程 MCP 服务器

远程 MCP 服务器通过 HTTP 连接，适合接入第三方服务或团队共享的 MCP 服务。

基本配置

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

url 指定远程服务器的地址，headers 用于传递自定义 HTTP 请求头，通常用于承载认证令牌。

完整配置选项

| 选项 | 类型 | 必填 | 说明 |
|------|------|------|------|
| type | String | 是 | 必须为 "remote" |
| url | String | 是 | 远程服务器 URL |
| headers | Object | 否 | 自定义请求头 |
| enabled | Boolean | 否 | 是否启用 |
| oauth | Object / false | 否 | OAuth 认证配置 |
| timeout | Number | 否 | 超时时间（毫秒），默认 5000 |

OAuth 认证

对于需要认证的远程 MCP 服务器，OpenCode 提供了完整的 OAuth 2.0 支持，包括自动发现、动态客户端注册和令牌管理。

自动认证（零配置）

大多数支持 OAuth 的 MCP 服务器不需要额外配置，OpenCode 会自动完成认证流程：

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

首次使用时，OpenCode 会检测服务器的 401 响应，自动启动 OAuth 流程，打开浏览器让你授权。授权完成后，令牌会安全地存储在 ~/.local/share/opencode/mcp-auth.json 中。

手动触发认证

你也可以手动管理认证状态：

# 触发认证
opencode mcp auth my-oauth-server

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

# 注销并删除凭据
opencode mcp logout my-oauth-server

# 调试认证问题
opencode mcp debug my-oauth-server

预注册客户端凭据

如果你已经向 MCP 服务提供商申请了客户端凭据，可以直接在配置中指定：

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

这里 {env:VARIABLE_NAME} 是 OpenCode 的环境变量引用语法，实际运行时会被替换为对应的环境变量值。

禁用 OAuth

如果服务器使用 API Key 而非 OAuth 认证，需要显式禁用 OAuth：

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

实战案例

下面我以三个常用的 MCP 服务器为例，展示从配置到使用的完整流程。

案例一：Sentry 错误监控

Sentry 是主流的前端和后端错误监控服务。接入 Sentry MCP 服务器后，你可以直接在终端内查询和分析错误。

配置：

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

认证：

opencode mcp auth sentry

这会打开浏览器跳转到 Sentry 授权页面，授权完成后返回终端。

使用：

查看我们项目中最近未解决的高优先级问题，用 sentry 工具

AI 助手会调用 Sentry MCP 获取实时错误数据，然后将结果用可读的格式呈现给你。你可以进一步追问：

第三个错误是什么时候开始的？影响的用户有多少？

这种交互方式让你无需离开编辑环境就能完成错误排查，特别适合"边写代码边解决问题"的工作流。

案例二：Context7 文档搜索

Context7 是 Upstash 开发的一个 MCP 服务器，能实时搜索最新的技术文档。对于查阅 API、框架文档非常有用。

基础配置（免费额度）：

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

使用 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}"
      }
    }
  }
}

使用前确保已设置环境变量：

export CONTEXT7_API_KEY="your-key-here"

使用示例：

帮我查一下 Cloudflare Workers 中如何缓存 JSON API 响应五分钟，用 context7 工具

Context7 会搜索最新文档并返回准确答案，效果远好于直接让 LLM 靠"记忆"回答——因为文档信息是实时的。

你还可以在项目的 AGENTS.md 中配置自动使用规则：

当需要搜索技术文档时，优先使用 context7 工具获取最新信息。

案例三：Grep by Vercel 代码搜索

Grep by Vercel 可以搜索 GitHub 上的公开代码，帮你快速找到某个 API 或模式的真实使用案例。

配置：

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

使用示例：

在 SST Astro 组件中设置自定义域名的正确方式是什么？使用 gh_grep 工具搜索 GitHub 上的示例

Grep 会在数百万个 GitHub 仓库中搜索相关代码片段，AI 助手则负责理解、总结这些片段，给你一个可以直接使用的答案。

MCP 服务器的管理

全局开关

你可以像管理内置工具一样管理 MCP 服务器。在 tools 字段中使用服务器名称来控制启停：

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

这样 my-mcp-bar 仍然可用，但 my-mcp-foo 被全局禁用了。

通配符批量管理

如果你有很多 MCP 服务器，可以使用 glob 模式批量操作：

{
  "tools": {
    "my-mcp*": false
  }
}

这行配置会禁用所有以 my-mcp 开头的服务器。注意，MCP 工具在注册时以服务器名称为前缀，所以 my-mcp_search 和 my-mcp_list 都属于 my-mcp 服务器。

支持的通配符：

* 匹配零个或多个任意字符
? 匹配恰好一个任意字符

按 Agent 分配

如果你的项目比较复杂，可能希望不同 Agent 使用不同的 MCP 服务器。典型做法是：全局禁用，然后按 Agent 开启需要的部分。

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "sentry": {
      "type": "remote",
      "url": "https://mcp.sentry.dev/mcp",
      "oauth": {}
    },
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp"
    }
  },
  "tools": {
    "sentry*": false,
    "context7*": false
  },
  "agent": {
    "debug": {
      "mode": "subagent",
      "tools": {
        "sentry*": true
      }
    },
    "research": {
      "mode": "subagent",
      "tools": {
        "context7*": true
      }
    }
  }
}

这样的配置使得：

debug agent 可以访问 Sentry 工具，但不能用 Context7
research agent 可以访问 Context7 工具，但不能用 Sentry
默认的 build agent 两个都不能用

注意事项与最佳实践

上下文消耗

MCP 服务器在启动时会向 LLM 暴露所有可用工具的描述。工具越多，消耗的上下文越多。举个例子，GitHub 官方的 MCP 服务器会注册大量工具，短短几次调用就可能超出上下文限制。

建议：

只接入你真正需要的 MCP 服务器
在不需要时通过 enabled: false 或 tools 字段关闭
优先按 Agent 分配，而非全局启用

本地 vs 远程的选择

| 场景 | 推荐类型 |
|------|----------|
| 访问本地文件系统或数据库 | 本地（local） |
| 调用第三方 SaaS API | 远程（remote） |
| 使用团队内部私有服务 | 远程（remote） |
| 需要 OAuth 授权的服务 | 远程 + OAuth |

调试技巧

当 MCP 服务器连接失败时，可以按以下步骤排查：

查看认证状态：

```bash
opencode mcp list
```

调试单个服务器：

```bash
opencode mcp debug <server-name>
```

确认服务器可用： 对于远程服务器，先用 curl 测试连通性。

检查超时： 如果网络较慢，适当增加 timeout 值（单位毫秒）。

组织级配置覆盖

如果你所在的组织通过 .well-known/opencode 端点提供了默认的 MCP 服务器配置，你可以在本地配置中覆盖它们。例如，组织提供了 Jira 服务器但默认关闭，你只需在本地配置中加上：

{
  "mcp": {
    "jira": {
      "type": "remote",
      "url": "https://jira.example.com/mcp",
      "enabled": true
    }
  }
}

你的本地配置优先于组织默认值。

总结

MCP 是连接 AI 编程助手与外部工具生态的关键桥梁。OpenCode 对 MCP 的支持使得你可以将 Sentry、Context7、GitHub Grep 等数十种工具无缝接入编程工作流，大幅减少上下文切换，提升开发效率。

回顾本文要点：

本地 MCP 服务器 适合访问本地资源和自定义工具
远程 MCP 服务器 适合接入第三方 SaaS 服务
OAuth 认证 实现了安全、自动化的服务授权
权限管理 通过 tools 字段和 Agent 分配实现精细化控制
上下文管理 是使用 MCP 时最需要注意的问题——按需启用，用完即走

有了 MCP，你的 OpenCode 不再是孤立的编程助手，而是连接了整个开发生态的操作中心。尝试接入你常用的开发工具，你会发现"一切都在终端里搞定"的开发体验有多么丝滑。

OpenCode MCP 服务器集成完全指南：让 AI 编程助手接入整个工具生态

OpenCode MCP 服务器集成完全指南：让 AI 编程助手接入整个工具生态

引言

MCP 服务器是什么

配置 MCP 服务器

本地 MCP 服务器

基本配置

完整配置选项

实战：接入 Everything 测试服务器

远程 MCP 服务器

基本配置

完整配置选项

OAuth 认证

自动认证（零配置）

手动触发认证

预注册客户端凭据

禁用 OAuth

实战案例

案例一：Sentry 错误监控

案例二：Context7 文档搜索

案例三：Grep by Vercel 代码搜索

MCP 服务器的管理

全局开关

通配符批量管理

按 Agent 分配

注意事项与最佳实践

上下文消耗

本地 vs 远程的选择

调试技巧

组织级配置覆盖

总结

叶云梦天

叶云梦天，专注微信，小程序，服务器管理，数据分析的信息博客