5.7b MCP 进阶

💡 一句话总结：掌握 OAuth 认证、权限管理和常用 MCP 服务配置。

📝 课程笔记

本课核心知识点整理：

学完你能做什么

使用 OAuth 认证连接安全服务
管理 MCP 工具的权限和启用状态
在规则文件中集成 MCP 使用
配置常用 MCP 服务

OAuth 认证

OpenCode 自动处理 OAuth 认证流程：

检测到 401 响应，启动 OAuth 流程
使用 动态客户端注册 (RFC 7591)（如服务器支持）
Token 安全存储在 ~/.local/share/opencode/mcp-auth.json

自动认证

大多数情况下无需特殊配置：

jsonc

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

首次使用时 OpenCode 会自动提示认证。

预注册客户端

如果服务器不支持动态注册，需要配置客户端凭证：

jsonc

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

管理命令

bash

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

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

# 列出所有 MCP 服务器
opencode mcp list

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

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

调试命令详解

当 MCP 连接出问题时，用 debug 命令诊断：

bash

opencode mcp debug my-oauth-server

输出示例：

MCP OAuth Debug

Server: my-oauth-server
URL: https://mcp.example.com/mcp
Auth status: ✓ authenticated
  Access token: eyJhbGciOiJSUzI1NiIs...
  Expires: 2026-02-15T12:00:00.000Z
  Refresh token: present

Testing connection...
HTTP response: 200 OK
✓ Server responded successfully

状态含义：

状态	说明
`authenticated`	已认证，可以正常使用
`expired`	Token 已过期，需要重新认证
`not authenticated`	未认证，需要运行 `opencode mcp auth`

服务器状态图标

opencode mcp list 输出中的图标含义：

图标	状态	说明
✓	connected	已连接，工具可用
○	disabled	已禁用，`enabled: false`
⚠	needs_auth	需要 OAuth 认证
✗	failed	连接失败，查看错误信息

示例输出：

MCP Servers

✓ filesystem connected
    npx -y @modelcontextprotocol/server-filesystem /projects
✓ context7 connected
    https://mcp.context7.com/mcp
○ disabled-server disabled
    npx -y some-command
✗ failed-server failed
    Connection timeout

禁用 OAuth

如果服务器使用 API Key 而非 OAuth：

jsonc

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

工具权限管理

MCP 工具注册时使用 {服务器名}_{工具名} 格式命名。

全局禁用

使用 permission 配置禁用 MCP 工具：

jsonc

{
  "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"]
    }
  },
  "permission": {
    "my-mcp-foo_*": "deny"
  }
}

使用通配符批量禁用：

jsonc

{
  "permission": {
    "my-mcp*": "deny"
  }
}

按 Agent 启用

全局禁用后，在特定 Agent 中启用：

jsonc

{
  "mcp": {
    "my-mcp": {
      "type": "local",
      "command": ["bun", "x", "my-mcp-command"]
    }
  },
  "permission": {
    "my-mcp*": "deny"
  },
  "agent": {
    "my-agent": {
      "permission": {
        "my-mcp*": "allow"
      }
    }
  }
}

通配符规则

* 匹配零个或多个任意字符
? 匹配正好一个字符
其他字符字面匹配

在规则文件中集成

在 AGENTS.md 或 .opencode/agents/*.md 中配置默认使用 MCP：

markdown

## MCP 使用规则

当需要查询文档时，使用 `context7` 工具。

当不确定如何实现某功能时，使用 `gh_grep` 搜索 GitHub 代码示例。

这样 AI 会自动选择合适的 MCP 工具，无需每次在提示词中指定。

工具自动发现与更新

工具命名规则

MCP 工具注册时使用 {服务器名}_{工具名} 格式：

filesystem     服务器的 read_file 工具 → filesystem_read_file
context7 服务器的 search 工具  → context7_search

自动发现机制

配置 MCP 服务器后，OpenCode 会自动发现服务器提供的所有工具：

连接到 MCP 服务器
调用 listTools 获取工具列表
将工具转换为 OpenCode 可用格式
添加到当前会话的工具集中

工具变更通知

如果 MCP 服务器的工具列表发生变化（新增/删除工具），OpenCode 会自动接收通知并更新：

服务器发送工具列表变更通知（notifications/tools/list_changed）
OpenCode 重新获取工具列表
无需重启 OpenCode

这意味着：升级 MCP 服务器版本后，新工具会自动可用。

常用 MCP 推荐

Sentry

连接 Sentry 监控平台，查询错误和问题：

jsonc

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

首次使用需要认证：

bash

opencode mcp auth sentry

使用示例：

use sentry 查看最近未解决的错误

Context7

搜索各种库和框架的文档：

jsonc

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

使用 API Key 获取更高速率限制：

jsonc

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

使用示例：

use context7 查询 Cloudflare Worker 如何缓存 JSON 响应

Grep by Vercel

搜索 GitHub 上的代码片段：

jsonc

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

使用示例：

use the gh_grep tool 搜索 SST 框架中如何配置自定义域名

Filesystem

本地文件系统操作（沙箱模式）：

jsonc

{
  "mcp": {
    "filesystem": {
      "type": "local",
      "command": [
        "npx", "-y", "@modelcontextprotocol/server-filesystem",
        "/path/to/allowed/directory"
      ]
    }
  }
}

Postgres

直接查询 PostgreSQL 数据库：

jsonc

{
  "mcp": {
    "postgres": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-postgres"],
      "environment": {
        "POSTGRES_CONNECTION_STRING": "{env:DATABASE_URL}"
      }
    }
  }
}

Puppeteer

浏览器自动化和网页抓取：

jsonc

{
  "mcp": {
    "puppeteer": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-puppeteer"]
    }
  }
}

Memory

持久化键值存储：

jsonc

{
  "mcp": {
    "memory": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-memory"]
    }
  }
}

SQLite

轻量级数据库操作：

jsonc

{
  "mcp": {
    "sqlite": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-sqlite", "/path/to/database.db"]
    }
  }
}

Slack

与 Slack 工作空间交互：

jsonc

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

踩坑提醒

现象	原因	解决
MCP 工具不出现	全局禁用或 Agent 未配置	检查 `permission` 配置
OAuth 认证失败	Token 过期或凭据无效	运行 `opencode mcp logout && opencode mcp auth`
状态显示 `needs_client_registration`	服务器不支持动态注册	在 `oauth` 中配置 `clientId`
上下文快速耗尽	启用了太多 MCP 工具	禁用不常用的 MCP，使用按 Agent 启用
工具名称冲突	多个 MCP 有同名工具	使用 `{服务器名}_{工具名}` 格式区分
认证后仍显示 needs_auth	Token 存储失败	检查 `~/.local/share/opencode/mcp-auth.json` 权限
命令格式错误	`command` 写成字符串而非数组	❌ `"command": "npx xxx"` → ✓ `"command": ["npx", "-y", "xxx"]`
URL 格式错误	URL 缺少协议前缀	❌ `"url": "example.com/mcp"` → ✓ `"url": "https://example.com/mcp"`
浏览器无法自动打开	在 SSH/远程环境下	OpenCode 会显示 URL，手动复制到浏览器打开
超时时间太短	`timeout` 设为 1000ms	远程服务器建议 2000+-10000ms，默认 30000ms
忘记启用服务器	`enabled: false` 但疑惑为什么不工作	默认就是启用的，检查是否误设为 `false`

本课小结

你学会了：

OAuth 认证：自动处理或手动配置客户端凭证
调试命令：opencode mcp debug 诊断连接问题
状态图标：✓ ○ ⚠ ✗ 四种状态的含义
权限管理：使用 permission 控制工具访问
工具自动发现：工具命名规则和变更通知机制
规则集成：在 AGENTS.md 中配置默认 MCP 使用
常用 MCP：Sentry、Context7、Grep、Postgres 等

下一课预告

下一课我们将学习 IDE 集成，让 OpenCode 与 VS Code、JetBrains 等编辑器无缝协作。

5.7b MCP 进阶 ​

📝 课程笔记 ​

学完你能做什么 ​

OAuth 认证 ​

自动认证 ​

预注册客户端 ​

管理命令 ​

调试命令详解 ​

服务器状态图标 ​

禁用 OAuth ​

工具权限管理 ​

全局禁用 ​

按 Agent 启用 ​

通配符规则 ​

在规则文件中集成 ​

工具自动发现与更新 ​

工具命名规则 ​

自动发现机制 ​

工具变更通知 ​

常用 MCP 推荐 ​

Sentry ​

Context7 ​

Grep by Vercel ​

Filesystem ​

Postgres ​

Puppeteer ​

Memory ​

SQLite ​

Slack ​

踩坑提醒 ​

本课小结 ​

相关资源 ​

下一课预告 ​

5.7b MCP 进阶

📝 课程笔记

学完你能做什么

OAuth 认证

自动认证

预注册客户端

管理命令

调试命令详解

服务器状态图标

禁用 OAuth

工具权限管理

全局禁用

按 Agent 启用

通配符规则

在规则文件中集成

工具自动发现与更新

工具命名规则

自动发现机制

工具变更通知

常用 MCP 推荐

Sentry

Context7

Grep by Vercel

Filesystem

Postgres

Puppeteer

Memory

SQLite

Slack

踩坑提醒

本课小结

相关资源

下一课预告