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 认证流程。当服务器需要认证时：

    1. 检测 401 响应并启动 OAuth 流程
    1. 在服务器支持的情况下使用动态客户端注册（RFC 7591）
    1. 安全地存储 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"]  
    }  
  }  
}

开发的核心原则

    1. 工具命名清晰：使用 动词_名词 格式，如 get_user、search_docs
    1. 描述准确：AI 根据描述决定何时调用工具，描述越准确越好
    1. 参数校验：使用 Zod（TypeScript）或类型注解（Python）进行参数校验
    1. 错误处理：返回 isError: true 标记错误，让 AI 知道调用失败
    1. 返回格式：始终返回结构化的文本内容
    1. 安全第一：不要在工具中执行不安全的操作（如直接执行用户输入的表达式），使用安全的解析器

📌 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]