叶云梦天

OpenCode MCP 服务器完全指南：用 Model Context Protocol 无限拓展 AI 编程助手的能力边界

引言

在 AI 编程助手的使用过程中，一个常见的痛点就是工具能力的边界限制。虽然 OpenCode 内置了丰富的工具系统（文件读写、代码搜索、终端执行等），但在实际开发中，我们常常需要与外部系统交互——查询 Sentry 的错误日志、搜索 GitHub 上的代码片段、查阅第三方服务的文档，或是操作 Jira 上的任务。如果每次都需要手动切换上下文，开发效率就会大打折扣。

OpenCode 的 MCP 服务器集成完美解决了这个问题。通过 Model Context Protocol（MCP），我们可以将任意外部工具无缝接入 AI 编程助手的工具箱，让 AI 直接调用这些工具完成复杂任务，而无需开发者手动切换窗口。本文将全面介绍 MCP 服务器的配置、使用和最佳实践。

什么是 MCP？

MCP（Model Context Protocol）是一种开放协议，由 Anthropic 提出，旨在为 AI 模型提供标准化的工具调用接口。你可以把它理解为 AI 世界的 USB 协议——只要设备（工具）遵循这个标准，AI 模型就能即插即用地与之交互。

在 OpenCode 中，MCP 服务器被当作内置工具一样对待。一旦配置完成，AI 助手会自动识别并使用这些工具，你只需要在提示词中引导它"使用某个 MCP 工具"即可。

OpenCode 支持两种类型的 MCP 服务器：

本地 MCP 服务器：作为子进程在本地运行，适合数据库查询、文件操作等本地工具
远程 MCP 服务器：通过 HTTP 连接，适合 API 集成、在线服务等场景

配置 MCP 服务器

所有 MCP 服务器的配置都放在 OpenCode 配置文件（opencode.jsonc）的 mcp 字段下。每个服务器需要一个唯一的名字作为标识。

本地 MCP 服务器

本地 MCP 服务器通过命令行启动，适合需要本地权限的工具。

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

配置字段说明：

| 字段 | 类型 | 说明 |
|------|------|------|
| type | string | 固定为 "local" |
| command | string[] | 启动命令及参数，如 ["npx", "-y", "some-package"] |
| cwd | string | 工作目录，相对路径从 workspace 解析 |
| environment | object | 环境变量 |
| enabled | boolean | 是否启用 |
| timeout | number | 工具获取超时时间，默认 5000ms |

远程 MCP 服务器

远程 MCP 服务器通过 URL 访问，适合集成在线服务。

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

OAuth 认证：零配置的安全连接

对于需要认证的远程 MCP 服务器，OpenCode 提供了自动化的 OAuth 支持。当服务器返回 401 时，OpenCode 会自动检测并启动 OAuth 流程。

自动认证

对于大多数支持 OAuth 的 MCP 服务器，你甚至不需要配置认证信息：

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

首次使用时，OpenCode 会弹出浏览器窗口让你完成授权。认证成功后，凭据会被安全地存储在 ~/.local/share/opencode/mcp-auth.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 认证：

# 手动触发某 MCP 服务器的 OAuth 流程
opencode mcp auth my-oauth-server

# 列出所有 MCP 服务器及其认证状态
opencode mcp list

# 清除存储的认证凭据
opencode mcp logout my-oauth-server

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

工具管理与粒度控制

MCP 注册的工具与 OpenCode 内置工具在同一个工具系统中，因此你可以通过 tools 字段进行精细化管理。

全局禁用

{
  "$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 模式批量禁用：

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

按 Agent 启用

如果有很多 MCP 服务器，你可能只想在特定的 Agent 中使用某些 MCP。可以全局禁用，然后按需在 Agent 配置中启用：

{
  "mcp": {
    "my-mcp": {
      "type": "local",
      "command": ["bun", "x", "my-mcp-command"],
      "enabled": true
    }
  },
  "tools": {
    "my-mcp*": false
  },
  "agent": {
    "my-agent": {
      "tools": {
        "my-mcp*": true
      }
    }
  }
}

注意：MCP 工具的注册名称带有服务器名前缀，因此要禁用某服务器的所有工具，可以在 glob 模式中使用带下划线的格式：

"tools": {
  "mymcpservername_*": false
}

实战案例

Sentry 错误监控

将 Sentry MCP 服务器接入 OpenCode，AI 可以直接查询错误信息：

{
  "mcp": {
    "sentry": {
      "type": "remote",
      "url": "https://mcp.sentry.dev/mcp",
      "oauth": {}
    }
  }
}

配置后执行 opencode mcp auth sentry 完成认证，就能在对话中使用了：

显示我项目中最新的未解决 Issue。use sentry

Context7 文档搜索

Context7 MCP 服务器可以搜索各种技术文档：

{
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp",
      "headers": {
        "CONTEXT7_API_KEY": "{env:CONTEXT7_API_KEY}"
      }
    }
  }
}

在 AGENTS.md 中添加规则让 AI 自动使用：

当你需要搜索技术文档时，使用 `context7` 工具。

Grep by Vercel 代码搜索

通过 Grep MCP 服务器，AI 可以直接搜索 GitHub 上的代码示例：

{
  "mcp": {
    "gh_grep": {
      "type": "remote",
      "url": "https://mcp.grep.app"
    }
  }
}

在提示词中引导使用：

在 SST Astro 组件中设置自定义域名的正确方法是什么？use the gh_grep tool

最佳实践与注意事项

1. 谨慎选择 MCP 服务器

MCP 工具会增加上下文占用。每个注册的工具都会消耗 Token，工具越多，留给真正代码上下文的 Token 就越少。建议只保留你真正需要的 MCP 服务器。

2. 注意 Token 消耗

某些 MCP 服务器（如 GitHub MCP 服务器）会返回大量数据，很容易超出上下文限制。使用时需要有明确的限定范围。

3. 利用 Agent 隔离

如果有大量 MCP 服务器，建议用 Agent 机制做隔离。创建专门的 Agent 处理特定领域任务，只为其启用相关的 MCP 工具。

4. 环境变量管理

敏感信息（API Key、密钥等）应该通过环境变量引用，而不是硬编码在配置文件中：

{
  "headers": {
    "Authorization": "Bearer {env:MY_API_KEY}"
  }
}

5. 合理使用 `enabled` 开关

临时不需要的 MCP 服务器可以设为 "enabled": false，保留配置但不启动，需要时再启用。

总结

MCP 服务器是 OpenCode 生态中最强大的扩展机制之一。它打破了 AI 编程助手的工具边界，让你可以将任意外部服务无缝接入 AI 工作流。从错误监控到文档搜索，从代码示例查询到项目管理，MCP 让 AI 编程助手真正成为你开发工作中的全能助手。

通过合理配置和精细化管理，你可以在不显著增加 Token 消耗的前提下，构建一个强大且高效的工具生态。建议先从一两个你实际需要的 MCP 服务器开始，逐步扩展，找到最适合自己工作流的组合。

OpenCode MCP 服务器完全指南：用 Model Context Protocol 无限拓展 AI 编程助手的能力边界

OpenCode MCP 服务器完全指南：用 Model Context Protocol 无限拓展 AI 编程助手的能力边界

引言

什么是 MCP？

配置 MCP 服务器

本地 MCP 服务器

远程 MCP 服务器

OAuth 认证：零配置的安全连接

自动认证

预注册客户端

命令行管理认证

工具管理与粒度控制

全局禁用

按 Agent 启用

实战案例

Sentry 错误监控

Context7 文档搜索

Grep by Vercel 代码搜索

最佳实践与注意事项

1. 谨慎选择 MCP 服务器

2. 注意 Token 消耗

3. 利用 Agent 隔离

4. 环境变量管理

5. 合理使用 enabled 开关

总结

叶云梦天

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

5. 合理使用 `enabled` 开关