OpenCode MCP深度实战:十款必备服务器打通全栈开发工具链
🔥 GitHub、数据库、Slack、浏览器……想象一下,一个 AI 工具就能把这些全部串起来。
从 10 个必装 MCP 服务器到按代理角色精细化权限控制,再到自定义开发入门——本文带你把 OpenCode 从“能写代码”升级成“能操控一切”。
📌 MCP 核心理念与架构解析
一句话说明
MCP(Model Context Protocol) 是一套开放协议,让 AI 编程代理可以对接外部工具和数据源。如果把 OpenCode 比作大脑,那么 MCP 就是它的手和眼睛——不仅能读写代码,还让它有能力查数据库、管 Issue、搜文档、操作云服务。
OpenCode 能力体系
内置工具层14 个基础工具
MCP 扩展层无限外部工具
文件读写 / Bash / 搜索
Sentry 错误追踪
Context7 文档查询
数据库操作
GitHub / Jira 集成
Slack 通知
自定义 API
MCP 在架构中的位置
回顾 OpenCode 的三层架构:
你的指令 → 代理层(怎么思考) → 工具层(能做什么) → 代码库
↑
MCP 扩展层(能连什么)
- • 内置工具:文件读写、Bash 执行、代码搜索等 14 个工具,开箱即用
- • MCP 工具:连接外部世界的桥梁,按需安装,扩展性几乎没有上限
一旦添加 MCP,其工具会自动与内置工具一起提供给 LLM 调用,无需额外配置。
本地 vs 远程:两种连接方式
| 特性 | 本地 MCP(local) | 远程 MCP(remote) |
|---|---|---|
| 运行方式 | 在你的机器上启动进程 | 连接云端服务 |
| 配置方式 | command 数组 |
url 字符串 |
| 典型场景 | 数据库、文件系统 | SaaS 服务(Sentry、GitHub) |
| 网络要求 | 不需要(纯本地) | 需要网络 |
| 认证方式 | 环境变量 / API Key | OAuth / API Key |
| 维护成本 | 需要本地依赖(Node.js) | 零维护 |
local
remote
OpenCode
MCP 类型
npx 启动本地进程
连接远程 URL
stdio 通信
HTTP/SSE 通信
⚠️ 注意:每个 MCP 服务器都会消耗上下文窗口。如果同时启用大量工具,Token 用量会迅速上升。建议按需开启,切忌贪多。尤其是像 GitHub MCP 这类工具数量众多的服务器,很容易吃掉大量上下文。
📌 必选 MCP 服务器 Top 10
下面是从数以万计的 MCP 服务器中筛选出的 10 个实用工具,覆盖研发全流程,并且都附带完整的 OpenCode 配置示例。
1. Sentry —— 错误追踪
在 OpenCode 中直接查看、排查线上错误。
场景:当你对 OpenCode 说“帮我看看线上最新的报错”,它会自动拉取 Sentry Issues,定位代码位置,并直接给出修复建议。
{
"mcp": {
"sentry": {
"type": "remote",
"url": "https://mcp.sentry.dev/mcp",
"oauth": {}
}
}
}
配置完成后,在终端进行认证:
opencode mcp auth sentry
浏览器会打开 Sentry OAuth 授权页面,授权后即可使用。
你:查看我项目最近未解决的错误,帮我修复
OpenCode:
🔍 使用 sentry 工具查询未解决的 Issues...
📋 找到 3 个未解决错误:
1. NullPointerException in UserService.java:42
2. TimeoutError in PaymentHandler.java:128
3. SQLException in OrderDAO.java:67
🔧 分析第 1 个错误...
📖 读取 UserService.java
✏️ 添加空值检查并修复
2. Context7 —— 文档查询
让 AI 总是基于最新框架文档工作,告别因训练数据过时产生的幻觉。
场景:当你问“React 19 的 use() Hook 怎么用”,Context7 会实时拉取最新文档,而不是依赖旧训练数据。
{
"mcp": {
"context7": {
"type": "remote",
"url": "https://mcp.context7.com/mcp"
}
}
}
注册免费账户可提升速率限制:
{
"mcp": {
"context7": {
"type": "remote",
"url": "https://mcp.context7.com/mcp",
"headers": {
"CONTEXT7_API_KEY": "{env:CONTEXT7_API_KEY}"
}
}
}
}
对话中直接使用:
你:帮我用 Next.js App Router 写一个用户认证模块,用 context7 查一下最新文档
💡 进阶用法:在 AGENTS.md 中添加规则
When you need to search docs, use context7 tools,AI 会在需要时自动调用。
3. 文件系统(Filesystem)
安全地访问项目目录之外的文件。
场景:需要读取配置模板、共享文档、日志文件等位于项目外部的资源。
{
"mcp": {
"filesystem": {
"type": "local",
"command": ["npx", "-y", "@anthropic/mcp-server-filesystem", "/path/to/allowed/dir"],
"enabled": true
}
}
}
可以指定多个可访问目录:
{
"mcp": {
"filesystem": {
"type": "local",
"command": [
"npx", "-y", "@anthropic/mcp-server-filesystem",
"/home/user/projects",
"/home/user/config-templates",
"/var/log/app"
]
}
}
}
4. 数据库(PostgreSQL / MySQL / SQLite)
让 AI 直接查询数据库,辅助数据分析与 Schema 设计。
场景:想“查看 users 表结构”或“分析最近一周注册数据趋势”,AI 可以直接执行 SQL 查询。
PostgreSQL:
{
"mcp": {
"postgres": {
"type": "local",
"command": ["npx", "-y", "@modelcontextprotocol/server-postgres"],
"environment": {
"POSTGRES_CONNECTION_STRING": "{env:DATABASE_URL}"
}
}
}
}
SQLite:
{
"mcp": {
"sqlite": {
"type": "local",
"command": ["npx", "-y", "@modelcontextprotocol/server-sqlite", "/path/to/database.db"]
}
}
}
MySQL:
{
"mcp": {
"mysql": {
"type": "local",
"command": ["npx", "-y", "@benborla29/mcp-server-mysql"],
"environment": {
"MYSQL_HOST": "{env:MYSQL_HOST}",
"MYSQL_PORT": "3306",
"MYSQL_USER": "{env:MYSQL_USER}",
"MYSQL_PASSWORD": "{env:MYSQL_PASSWORD}",
"MYSQL_DATABASE": "{env:MYSQL_DATABASE}"
}
}
}
}
⚠️ 安全提示:强烈建议对数据库 MCP 采用按代理角色权限控制(见后文),确保只有 Build 代理可查询数据,且禁止执行
DROP、DELETE等危险操作。
5. GitHub
在 OpenCode 中直接操作 GitHub:查看 PR、管理 Issue、创建 Release。
{
"mcp": {
"github": {
"type": "local",
"command": ["npx", "-y", "@modelcontextprotocol/server-github"],
"environment": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "{env:GITHUB_TOKEN}"
}
}
}
}
使用场景:
你:列出这个仓库最近一周的 PR,看看有没有未审查的
你:创建一个 Issue,标题是「修复用户登录超时问题」,标签 bug
你:查看 PR #42 的代码变更,帮我审查一下
⚠️ Token 消耗提醒:GitHub MCP 工具数量较多,会占用大量上下文。建议在需要时开启,用完立即关闭。
6. Jira / Linear —— 项目管理
让 AI 能读取和更新你的项目管理工具。
Jira(远程方式):
{
"mcp": {
"jira": {
"type": "remote",
"url": "https://mcp.atlassian.com/v1/mcp",
"oauth": {}
}
}
}
认证方式:
opencode mcp auth jira
Linear(本地方式):
{
"mcp": {
"linear": {
"type": "local",
"command": ["npx", "-y", "@anthropic/mcp-server-linear"],
"environment": {
"LINEAR_API_KEY": "{env:LINEAR_API_KEY}"
}
}
}
}
使用场景:
你:查看 Sprint 当前的进度,有哪些未完成的任务
你:把 BUG-123 的状态改为 In Progress,并添加评论「正在修复中」
7. Slack —— 团队通知
让 AI 读取 Slack 消息、发送通知,将开发流程自动化。
{
"mcp": {
"slack": {
"type": "local",
"command": ["npx", "-y", "@modelcontextprotocol/server-slack"],
"environment": {
"SLACK_BOT_TOKEN": "{env:SLACK_BOT_TOKEN}",
"SLACK_TEAM_ID": "{env:SLACK_TEAM_ID}"
}
}
}
}
使用场景:
你:在 #dev-team 频道发一条消息:「v2.1.0 已发布,请更新本地环境」
你:查看 #alerts 频道最近的告警消息,帮我分析有没有需要紧急处理的
8. 代码搜索(Grep by Vercel)
在 GitHub 中搜索代码示例,快速找到最佳实践。
{
"mcp": {
"gh_grep": {
"type": "remote",
"url": "https://mcp.grep.app"
}
}
}
使用场景:
你:SST 的 Astro 组件怎么配置自定义域名?用 gh_grep 搜一下
你:帮我搜一下开源项目中 FastAPI + SQLAlchemy 的最佳分页实现
💡 搭配建议:Context7 负责官方文档,Grep 负责社区实践——两者结合效果最佳。
9. Google Drive
读取团队共享文档,让 AI 获取产品需求、设计稿等资料。
{
"mcp": {
"google-drive": {
"type": "local",
"command": ["npx", "-y", "@anthropic/mcp-server-google-drive"],
"environment": {
"GOOGLE_OAUTH_CLIENT_ID": "{env:GOOGLE_CLIENT_ID}",
"GOOGLE_OAUTH_CLIENT_SECRET": "{env:GOOGLE_CLIENT_SECRET}"
}
}
}
}
使用场景:
你:读取 Google Drive 里的「Q2 产品需求文档」,帮我根据需求拆分开发任务
10. 自定义 API(通用 HTTP 服务器)
将任意 REST API 转换成 MCP 工具,连接内部服务。
{
"mcp": {
"internal-api": {
"type": "remote",
"url": "https://mcp.your-company.com/api",
"headers": {
"Authorization": "Bearer {env:INTERNAL_API_TOKEN}"
},
"timeout": 10000
}
}
}
对于更复杂的场景,可以借助社区工具将 REST API 快速转成 MCP 服务器,例如 Composio[1] 或 Pipedream[2] 等平台已经提供了数百个预构建的 MCP 服务器。
完整的 Top 10 配置汇总
// opencode.json —— 推荐 MCP 配置合集
{
"$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"
},
"filesystem": {
"type": "local",
"command": ["npx", "-y", "@anthropic/mcp-server-filesystem", "/home/user/projects"]
},
"postgres": {
"type": "local",
"command": ["npx", "-y", "@modelcontextprotocol/server-postgres"],
"environment": {
"POSTGRES_CONNECTION_STRING": "{env:DATABASE_URL}"
}
},
"github": {
"type": "local",
"command": ["npx", "-y", "@modelcontextprotocol/server-github"],
"environment": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "{env:GITHUB_TOKEN}"
}
},
"jira": {
"type": "remote",
"url": "https://mcp.atlassian.com/v1/mcp",
"oauth": {}
},
"slack": {
"type": "local",
"command": ["npx", "-y", "@modelcontextprotocol/server-slack"],
"environment": {
"SLACK_BOT_TOKEN": "{env:SLACK_BOT_TOKEN}",
"SLACK_TEAM_ID": "{env:SLACK_TEAM_ID}"
}
},
"gh_grep": {
"type": "remote",
"url": "https://mcp.grep.app"
},
"google-drive": {
"type": "local",
"command": ["npx", "-y", "@anthropic/mcp-server-google-drive"],
"environment": {
"GOOGLE_OAUTH_CLIENT_ID": "{env:GOOGLE_CLIENT_ID}",
"GOOGLE_OAUTH_CLIENT_SECRET": "{env:GOOGLE_CLIENT_SECRET}"
}
},
"internal-api": {
"type": "remote",
"url": "https://mcp.your-company.com/api",
"headers": {
"Authorization": "Bearer {env:INTERNAL_API_TOKEN}"
}
}
}
}
📌 MCP 配置方法详解
基础格式
所有 MCP 配置都写在 opencode.json 的 mcp 字段中,每个服务器指定一个唯一名称:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"<服务器名称>": {
"type": "local | remote",
"enabled": true,
// 本地服务器特有字段
"command": ["...", "..."],
"environment": { "KEY": "VALUE" },
// 远程服务器特有字段
"url": "https://...",
"headers": { "Key": "Value" },
"oauth": {},
// 通用字段
"timeout": 5000
}
}
}
本地服务器配置选项
| 选项 | 类型 | 必填 | 描述 |
|---|---|---|---|
type |
字符串 | 是 | 必须为 "local" |
command |
数组 | 是 | 启动命令及参数 |
environment |
对象 | 否 | 环境变量 |
enabled |
布尔值 | 否 | 是否启用(默认 true) |
timeout |
数字 | 否 | 获取工具超时(毫秒,默认 5000) |
远程服务器配置选项
| 选项 | 类型 | 必填 | 描述 |
|---|---|---|---|
type |
字符串 | 是 | 必须为 "remote" |
url |
字符串 | 是 | 远程服务器地址 |
headers |
对象 | 否 | 请求头 |
enabled |
布尔值 | 否 | 是否启用(默认 true) |
oauth |
对象/false | 否 | OAuth 配置 |
timeout |
数字 | 否 | 获取工具超时(毫秒,默认 5000) |
远程服务器 + OAuth
OpenCode 会自动处理远程 MCP 的 OAuth 认证流程。当服务器需要认证时:
-
- 检测 401 响应并启动 OAuth 流程
-
- 在服务器支持的情况下使用动态客户端注册(RFC 7591)
-
- 安全地存储 Token 供后续使用
自动认证(推荐):
{
"mcp": {
"my-oauth-server": {
"type": "remote",
"url": "https://mcp.example.com/mcp",
"oauth": {}
}
}
}
首次使用时,OpenCode 会提示进行浏览器授权。也可以手动触发:
# 认证某个 MCP 服务器
opencode mcp auth my-oauth-server
# 查看所有 MCP 的认证状态
opencode mcp auth list
# 登出(删除凭据)
opencode mcp logout my-oauth-server
预注册客户端凭据:
如果你已经有了 OAuth 客户端 ID 和 Secret:
{
"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"
}
}
}
}
禁用 OAuth:
如果服务器使用 API Key 而非 OAuth:
{
"mcp": {
"my-api-key-server": {
"type": "remote",
"url": "https://mcp.example.com/mcp",
"oauth": false,
"headers": {
"Authorization": "Bearer {env:MY_API_KEY}"
}
}
}
}
环境变量注入
OpenCode 配置支持两种变量替换方式:
环境变量:使用 {env:VARIABLE_NAME} 引用
{
"mcp": {
"sentry": {
"type": "local",
"command": ["npx", "-y", "@sentry/mcp-server"],
"environment": {
"SENTRY_API_TOKEN": "{env:SENTRY_TOKEN}",
"SENTRY_ORG": "{env:SENTRY_ORG}"
}
}
}
}
如果环境变量未设置,会被替换为空字符串。
文件内容:使用 {file:path/to/file} 引用
{
"mcp": {
"my-server": {
"type": "remote",
"url": "https://mcp.example.com",
"headers": {
"Authorization": "Bearer {file:~/.secrets/mcp-token}"
}
}
}
}
💡 最佳实践:永远不要把 API Key、Token 等敏感信息直接写在配置文件中。一律使用环境变量引用,再在
.zshrc或.bashrc中设置环境变量。
启用与禁用
用 enabled 字段控制:
{
"mcp": {
"github": {
"type": "local",
"command": ["npx", "-y", "@modelcontextprotocol/server-github"],
"environment": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "{env:GITHUB_TOKEN}"
},
"enabled": false
}
}
}
当需要临时禁用某个服务器而不从配置中删除时,设为 false 即可。
📌 按代理角色精细控制 MCP 权限
为什么需要按代理控制?
不同代理承担不同职责,对 MCP 工具的权限需求也各不相同:
| 代理 | 数据库查询 | 数据库写入 | Sentry | GitHub | Slack |
|---|---|---|---|---|---|
| Build | ask | ask | allow | allow | ask |
| Explore | allow | deny | allow | allow | deny |
| 自定义审计 | allow | deny | allow | deny | deny |
配置方法
通过两步实现精细化控制:
第一步:在 mcp 字段注册 MCP 服务器。
第二步:在 agent 字段中按代理配置 MCP 工具权限。
{
"mcp": {
"database": {
"type": "local",
"command": ["npx", "-y", "@modelcontextprotocol/server-postgres"],
"environment": {
"POSTGRES_CONNECTION_STRING": "{env:DATABASE_URL}"
}
}
},
"agent": {
"build": {
"mcp": {
"database": {
"tools": {
"query": "ask",
"migrate": "deny",
"insert": "ask",
"delete": "deny"
}
}
}
},
"explore": {
"mcp": {
"database": {
"tools": {
"query": "allow",
"migrate": "deny",
"insert": "deny",
"delete": "deny"
}
}
}
}
}
}
全局禁用 + 按代理启用
当 MCP 服务器很多时,可以先全局禁用,再按需在特定代理中启用:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"sentry": {
"type": "remote",
"url": "https://mcp.sentry.dev/mcp",
"oauth": {}
},
"github": {
"type": "local",
"command": ["npx", "-y", "@modelcontextprotocol/server-github"],
"environment": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "{env:GITHUB_TOKEN}"
}
},
"postgres": {
"type": "local",
"command": ["npx", "-y", "@modelcontextprotocol/server-postgres"],
"environment": {
"POSTGRES_CONNECTION_STRING": "{env:DATABASE_URL}"
}
}
},
"tools": {
"sentry*": false,
"github*": false,
"postgres*": false
},
"agent": {
"build": {
"tools": {
"sentry*": true,
"github*": true,
"postgres*": true
}
},
"explore": {
"tools": {
"sentry*": true,
"postgres*": true
}
},
"security-auditor": {
"description": "安全审计代理,只能读取信息",
"tools": {
"sentry*": true,
"postgres*": true,
"github*": true
}
}
}
}
Glob 模式规则
在 tools 中支持通配符:
- •
*匹配零个或多个任意字符(如"sentry*"匹配sentry_list_issues、sentry_get_error等) - •
?匹配恰好一个字符 - • 其他字符按字面值匹配
{
"tools": {
"my-mcp*": false
}
}
上面的配置会禁用所有以 my-mcp 开头的工具。
📌 自定义 MCP 服务器开发实战
基本结构
每一个 MCP 服务器本质上都是一个进程,通过标准输入/输出与 OpenCode 通信,采用 JSON-RPC 协议交换消息。
stdin/stdoutJSON-RPC
OpenCode
MCP Server
工具 1
工具 2
资源
一个 MCP 服务器需要实现:
- • 工具(Tools):AI 可以调用的函数
- • 资源(Resources):AI 可以读取的数据
使用 TypeScript 开发(推荐)
第一步:创建项目。
mkdir my-mcp-server && cd my-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk zod
第二步:编写服务器代码。
// index.ts
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
// 创建 MCP 服务器
const server = new McpServer({
name: "my-tools",
version: "1.0.0"
});
// 注册一个工具:获取天气
server.tool(
"get_weather",
"获取指定城市的天气信息",
{ city: z.string().describe("城市名称") },
async ({ city }) => {
// 这里替换为实际的 API 调用
const weather = {
city,
temperature: "22°C",
condition: "晴"
};
return {
content: [{ type: "text", text: JSON.stringify(weather, null, 2) }]
};
}
);
// 注册另一个工具:内部 API 查询
server.tool(
"query_internal_api",
"查询公司内部 API 获取数据",
{
endpoint: z.string().describe("API 端点路径"),
method: z.enum(["GET", "POST"]).describe("HTTP 方法")
},
async ({ endpoint, method }) => {
try {
const response = await fetch(`https://api.company.com${endpoint}`, {
method,
headers: { "Authorization": "Bearer process.env.API_TOKEN" }
});
const data = await response.json();
return {
content: [{ type: "text", text: JSON.stringify(data, null, 2) }]
};
} catch (error) {
return {
content: [{ type: "text", text: `API 请求失败: ${error}` }],
isError: true
};
}
}
);
// 启动服务器
const transport = new StdioServerTransport();
await server.connect(transport);
第三步:配置到 OpenCode。
{
"mcp": {
"my-tools": {
"type": "local",
"command": ["npx", "tsx", "/path/to/my-mcp-server/index.ts"]
}
}
}
或者先编译再使用:
{
"mcp": {
"my-tools": {
"type": "local",
"command": ["node", "/path/to/my-mcp-server/dist/index.js"]
}
}
}
使用 Python 开发
mkdir my-mcp-server && cd my-mcp-server
python3 -m venv venv
source venv/bin/activate
pip install mcp
# server.py
from mcp.server.fastmcp import FastMCP
mcp = FastMCP("my-tools")
@mcp.tool()
def get_weather(city: str) -> str:
"""获取指定城市的天气信息"""
import json
weather = {
"city": city,
"temperature": "22°C",
"condition": "晴"
}
return json.dumps(weather, ensure_ascii=False, indent=2)
@mcp.tool()
def search_docs(query: str) -> str:
"""搜索内部文档"""
# 替换为实际的搜索逻辑
return f"搜索 '{query}' 的结果:..."
if __name__ == "__main__":
mcp.run()
配置到 OpenCode:
{
"mcp": {
"my-tools": {
"type": "local",
"command": ["/path/to/my-mcp-server/venv/bin/python", "/path/to/my-mcp-server/server.py"]
}
}
}
开发的核心原则
-
- 工具命名清晰:使用
动词_名词格式,如get_user、search_docs
- 工具命名清晰:使用
-
- 描述准确:AI 根据描述决定何时调用工具,描述越准确越好
-
- 参数校验:使用 Zod(TypeScript)或类型注解(Python)进行参数校验
-
- 错误处理:返回
isError: true标记错误,让 AI 知道调用失败
- 错误处理:返回
-
- 返回格式:始终返回结构化的文本内容
-
- 安全第一:不要在工具中执行不安全的操作(如直接执行用户输入的表达式),使用安全的解析器
📌 MCP 故障诊断与修复
常见问题速查
| 问题 | 原因 | 解决方法 |
|---|---|---|
| MCP 服务器启动失败 | 本地依赖缺失 | 运行 npx 命令确认包能正常下载 |
| 工具列表为空 | 超时或连接失败 | 增加 timeout 值 |
| OAuth 认证失败 | 浏览器未打开或回调超时 | 手动执行 opencode mcp auth <name> |
| Token 消耗过快 | MCP 工具描述占用过多上下文 | 减少启用的 MCP 数量 |
| 环境变量未生效 | 变量名错误或未导出 | 检查 echo $VAR_NAME 是否有值 |
command not found |
npx 路径问题 | 使用完整路径:/usr/local/bin/npx |
调试命令
# 查看 MCP 服务器认证状态
opencode mcp auth list
# 调试特定服务器的连接和 OAuth 流程
opencode mcp debug <server-name>
# 手动触发认证
opencode mcp auth <server-name>
# 删除已存储的凭据
opencode mcp logout <server-name>
调试本地 MCP 服务器
如果本地 MCP 启动有问题,可以先手动运行命令测试:
# 直接运行 command 中的命令,看是否有输出
npx -y @modelcontextprotocol/server-postgres
# 检查环境变量是否正确
echo $DATABASE_URL
# 查看 Node.js / npm 版本
node --version && npm --version
调试远程 MCP 服务器
# 测试 URL 是否可达
curl -I https://mcp.sentry.dev/mcp
# 测试带认证头的请求
curl -H "Authorization: Bearer $YOUR_TOKEN" https://mcp.example.com/mcp
💡 高级技巧与最佳实践
1. 在 AGENTS.md 中设置 MCP 使用规则
在项目的 AGENTS.md 中添加规则,让 AI 自动知道何时使用哪个 MCP:
## MCP 使用规则
- 查询最新文档时,使用 context7 工具
- 查看线上错误时,使用 sentry 工具
- 搜索代码示例时,使用 gh_grep 工具
- 数据库相关操作,使用 postgres 工具,但禁止执行 DROP 和 DELETE
2. 临时启用/禁用 MCP
在对话过程中,可以通过配置文件的 enabled 字段快速切换:
// 日常开发时禁用 GitHub MCP(节省上下文)
"github": { "enabled": false }
// 需要处理 Issue 时启用
"github": { "enabled": true }
3. 多环境配置
利用 OpenCode 配置的优先级机制,实现不同环境的 MCP 管理:
- • 全局配置(
~/.config/opencode/opencode.json):通用的 Sentry、Context7 等 - • 项目配置(项目根目录
opencode.json):项目特定的数据库、API 等
全局配置
项目配置
最终生效配置
Sentry ✅Context7 ✅
PostgreSQL ✅Internal API ✅
Sentry ✅ + Context7 ✅+ PostgreSQL ✅ + Internal API ✅
4. 组织级远程默认配置
组织可以通过 .well-known/opencode 端点提供默认的 MCP 配置。这些服务器可能默认处于禁用状态,团队成员可以按需启用:
// 组织远程默认配置(.well-known/opencode)
{
"mcp": {
"jira": {
"type": "remote",
"url": "https://jira.example.com/mcp",
"enabled": false
},
"confluence": {
"type": "remote",
"url": "https://confluence.example.com/mcp",
"enabled": false
}
}
}
// 你在本地配置中启用需要的服务器
{
"mcp": {
"jira": {
"type": "remote",
"url": "https://jira.example.com/mcp",
"enabled": true
}
}
}
5. Token 消耗优化策略
MCP 工具描述会占用上下文空间。优化策略:
- • 按需启用:只启用当前任务需要的 MCP
- • 使用 Glob 禁用:用
"my-mcp*": false批量禁用不需要的工具 - • 按代理精细控制:只在 Build 代理中启用写操作类 MCP
- • 选择轻量 MCP:优先选择远程 MCP(零本地开销),本地 MCP 只在必要时使用
⚠️ 常见问题解答
Q1: 本地 MCP 需要什么环境?
本地 MCP 需要 Node.js(建议 v18+),因为大部分通过 npx 启动。如果你使用 Python MCP,则需要对应的 Python 环境。
Q2: 远程 MCP 会不会慢?
远程 MCP 通过 HTTP/SSE 通信,通常响应很快。对于实时性要求高的场景(如数据库查询),本地 MCP 可能更快。
Q3: 一个项目可以配多少个 MCP?
没有硬性限制,但建议控制在 5 个以内。每多一个 MCP 都会消耗上下文 Token,过多会导致 AI 可用的上下文空间不足。
Q4: MCP 和内置工具冲突了怎么办?
如果 MCP 工具与内置工具名称冲突,内置工具优先。你可以通过 tools 配置来显式管理优先级。
Q5: 如何查看当前加载了哪些 MCP 工具?
在 OpenCode 对话中,AI 可以看到所有可用工具列表(包括 MCP 工具)。你也可以通过调试命令查看:
opencode mcp debug <server-name>
Q6: MCP 服务器会访问我的代码吗?
本地 MCP 进程在你的机器上运行,只拥有你给予它的权限。远程 MCP 通过 HTTPS 通信,数据经过加密。建议:
- • 敏感数据使用环境变量注入
- • 危险操作(数据库写入)设置为
ask权限 - • 只使用来源可信的 MCP 服务器
Q7: 如何在不修改配置的情况下临时使用某个 MCP?
可以使用 OPENCODE_CONFIG_CONTENT 环境变量内联配置:
export OPENCODE_CONFIG_CONTENT='{"mcp":{"temp":{"type":"remote","url":"https://temp.example.com/mcp"}}}'
opencode
📚 精华总结
MCP 的核心价值 = 让 OpenCode 从代码编辑器进化为全栈开发平台
| 层级 | 核心内容 |
|---|---|
| 概念 | MCP 是连接外部工具的开放协议,分本地和远程两种方式 |
| 必装 Top 10 | Sentry、Context7、文件系统、数据库、GitHub、Jira/Linear、Slack、代码搜索、Google Drive、自定义 API |
| 配置 | type 必填,本地用 command,远程用 url,环境变量用 {env:VAR} |
| 权限 | 先全局禁用,再按代理启用——最小权限原则 |
| 自定义开发 | TypeScript SDK 或 Python SDK,注册工具函数,通过 stdio 通信 |
| 故障排查 | opencode mcp auth/debug/logout 三件套 |
记住一个原则:MCP 是扩展能力的利器,但不要贪多。按需启用,精细控制。
🔗 延伸阅读
- • OpenCode MCP 服务器文档(官方)[3]
- • OpenCode 配置参考(官方)[4]
- • MCP 协议规范[5]
- • MCP TypeScript SDK[6]
- • Awesome MCP Servers(社区精选)[7]
- • 代理与工具——OpenCode 智能操作体系[8]
- • AGENTS.md + Skills——让 AI 理解你的项目[9]