OpenCode MCP 服务器完全指南：用模型上下文协议扩展 AI 编程助手的工具生态

引言

在 AI 编程助手的世界里，模型的能力边界决定了它能够完成的任务范围。OpenCode 作为一个开源的 AI 编程代理，内置了文件操作、终端执行、代码搜索等丰富的工具集。但现实世界的开发场景千变万化——你可能需要查询 Sentry 错误、搜索 GitHub 代码片段、读取项目文档，甚至操作数据库。这时，MCP（Model Context Protocol，模型上下文协议）服务器就派上了用场。

MCP 是一种开放协议，它定义了 AI 模型如何与外部工具和服务进行交互。你可以把它理解为 AI 世界的"USB 接口"——通过这个标准化的协议，OpenCode 可以连接任意实现了 MCP 协议的工具和服务，从而无限扩展自己的能力边界。本文将深入讲解 OpenCode 中 MCP 服务器的配置、使用和管理，帮助你打造一个真正全能的 AI 编程助手。

什么是 MCP？

MCP 由 Anthropic 提出并开源，旨在解决 AI 模型与外部工具交互的标准化问题。在 MCP 的架构中，有两个核心角色：

  • MCP 客户端（Client）：即 AI 编程助手，如 OpenCode
  • MCP 服务器（Server）：提供特定功能的工具服务

当你向 OpenCode 发送一个需要调用外部工具的指令时，OpenCode 会通过 MCP 协议将请求转发给配置好的 MCP 服务器，服务器执行相应操作后返回结果。整个过程对用户来说是透明的，你只需要自然地描述需求即可。

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

  • 本地 MCP 服务器：在本地运行的进程，通过标准输入输出（stdio）通信
  • 远程 MCP 服务器：通过网络 API 访问的服务，通过 HTTP/HTTPS 通信

配置 MCP 服务器

MCP 服务器通过 OpenCode 的配置文件 opencode.json 或 opencode.jsonc 进行管理。所有 MCP 配置都放在 mcp 字段下，每个服务器需要有一个唯一的名称。

基础配置结构

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-mcp-server": {
      "type": "local",
      "command": ["npx", "-y", "my-mcp-command"],
      "enabled": true
    }
  }
}
  • type：服务器类型，"local" 或 "remote"
  • command（本地）：启动命令及参数数组
  • url（远程）：远程服务器地址
  • enabled：是否在启动时启用
  • environment（本地）：传递给进程的环境变量
  • headers（远程）：HTTP 请求头
  • timeout：超时时间，默认 5000ms

启用和禁用

默认情况下，MCP 服务器在配置后会自动启用。你也可以显式控制：

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

当 enabled 设置为 false 时，服务器仍然保留在配置中，但不会被加载。这在需要临时禁用某个服务器时非常有用。

本地 MCP 服务器

本地 MCP 服务器作为子进程运行，通过标准输入输出与 OpenCode 通信。这是最常用的方式，适合运行在本地机器上的工具。

配置示例

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

带环境变量的配置

某些 MCP 服务器需要 API 密钥或其他环境变量才能正常工作：

{
  "mcp": {
    "my-db-mcp": {
      "type": "local",
      "command": ["npx", "-y", "@my/db-mcp"],
      "environment": {
        "DATABASE_URL": "postgresql://localhost:5432/mydb",
        "API_KEY": "{env:MY_API_KEY}"
      }
    }
  }
}

{env:MY_API_KEY} 语法表示从系统环境变量 MY_API_KEY 中读取值，避免在配置文件中硬编码敏感信息。

指定工作目录

某些 MCP 服务器需要在特定目录下运行，可以使用 cwd 参数：

{
  "mcp": {
    "my-mcp": {
      "type": "local",
      "command": ["node", "server.js"],
      "cwd": "./mcp-servers/my-mcp"
    }
  }
}

远程 MCP 服务器

远程 MCP 服务器通过网络 API 提供服务，适合对接 SaaS 服务或团队内部部署的工具。

基本配置

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

OAuth 认证

OpenCode 对远程 MCP 服务器的 OAuth 认证提供了完善的支持。当服务器返回 401 状态码时，OpenCode 会自动启动 OAuth 流程。

对于大多数支持 OAuth 的 MCP 服务器，无需额外配置：

{
  "mcp": {
    "my-oauth-server": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp"
    }
  }
}

如果需要预注册客户端凭证：

{
  "mcp": {
    "my-oauth-server": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp",
      "oauth": {
        "clientId": "{env:MCP_CLIENT_ID}",
        "clientSecret": "{env:MCP_CLIENT_SECRET}",
        "scope": "tools:read tools:execute"
      }
    }
  }
}

OpenCode 还提供了 CLI 命令来管理 OAuth 凭证：

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

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

# 移除已存储的凭证
opencode mcp logout my-oauth-server

# 调试 OAuth 连接
opencode mcp debug my-oauth-server

认证成功后，凭证会被安全存储在 ~/.local/share/opencode/mcp-auth.json 中。

覆盖远程默认配置

企业组织可以通过 .well-known/opencode 端点提供默认的 MCP 服务器配置。这些服务器默认可能是禁用的，用户可以按需启用：

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

本地配置会覆盖远程默认值。

管理 MCP 工具

MCP 服务器注册的工具会与 OpenCode 内置的工具一起出现在工具列表中。你可以通过 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
  }
}

使用 Glob 模式批量管理

当你有大量 MCP 服务器时，可以使用 glob 模式批量操作：

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

上述配置会禁用所有以 my-mcp 开头的服务器工具。MCP 工具的注册名称以服务器名称为前缀，所以可以使用 "servername_*" 模式来匹配特定服务器的所有工具。

按代理（Agent）管理

如果你有多个子代理，可以为不同的代理分配不同的 MCP 工具：

{
  "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 工具以避免上下文膨胀，然后只对特定代理启用需要的工具。

实战案例

集成 Sentry 错误追踪

Sentry 的 MCP 服务器可以让你直接在 OpenCode 中查询项目错误和问题：

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

配置后，通过命令行完成 OAuth 认证：

opencode mcp auth sentry

之后你可以在对话中直接提问：

显示我项目中最新未解决的问题，使用 sentry。

集成 Context7 文档搜索

Context7 是一个文档搜索引擎，可以帮你查找各种框架和工具的文档：

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

如果需要更高的速率限制，可以注册免费账号并使用 API 密钥：

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

在 AGENTS.md 中添加规则，让 OpenCode 自动使用 Context7：

当需要搜索文档时，使用 context7 工具。

集成 Grep by Vercel

Grep by Vercel 可以搜索 GitHub 上的代码片段，非常实用：

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

在 AGENTS.md 中配置自动使用：

如果不确定如何实现某个功能，使用 gh_grep 搜索 GitHub 上的代码示例。

注意事项与最佳实践

上下文管理

MCP 服务器会消耗上下文令牌。每添加一个 MCP 服务器，它的工具列表和描述都会被注入到系统提示中。因此，建议只启用你真正需要的服务器。某些服务器（如 GitHub MCP 服务器）可能会产生大量令牌，容易超出上下文限制。

超时设置

默认超时时间为 5 秒。如果你的 MCP 服务器响应较慢（比如需要启动时间），可以适当调整：

{
  "mcp": {
    "my-slow-mcp": {
      "type": "local",
      "command": ["node", "slow-server.js"],
      "timeout": 30000
    }
  }
}

安全实践

  • 敏感信息（API 密钥、数据库连接串等）应通过环境变量传入，而非直接写在配置文件中
  • 对于本地 MCP 服务器，确保 command 中的可执行文件来源可信
  • 定期审查启用的 MCP 服务器，移除不再需要的

远程 MCP 关闭 OAuth

如果远程 MCP 服务器使用 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 服务器是 OpenCode 生态系统中极为强大的一环。通过这个标准化的协议，OpenCode 的能力不再局限于内置工具，而是可以无限扩展到任何支持 MCP 的服务上。本文详细讲解了本地和远程 MCP 服务器的配置方法、OAuth 认证流程、工具管理策略以及多个实战案例。

在实际使用中，建议从最需要的工具开始，逐步添加 MCP 服务器，同时注意控制上下文令牌的消耗。合理配置的 MCP 服务器能让 OpenCode 从一个代码编辑器升级为全能的开发助手——查错误、搜文档、找代码示例，一气呵成。

随着 MCP 生态的不断发展，越来越多的服务和工具开始提供 MCP 接口。掌握 MCP 服务器的配置和管理，就是掌握了扩展 AI 编程助手能力的钥匙。立即动手配置你的第一个 MCP 服务器，体验 OpenCode 真正的潜力吧！

叶云梦天

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