首页 > 专题 > AI编程 > 文章详情
返回 AI编程

5、OpenCode MCP服务器操作手册

2026年02月08日 26 阅读 AI编程

OpenCode MCP服务器操作手册

什么是MCP服务器

MCP（Model Context Protocol）是Anthropic推出的开放协议，用于连接AI助手与外部工具。OpenCode支持添加本地和远程MCP服务器，扩展AI的工具能力。

第一步：了解两种MCP服务器

本地MCP服务器

  • 在本地运行，通过命令行启动
  • 适合访问本地文件系统、数据库等
  • 配置示例："type": "local"

远程MCP服务器

  • 运行在远程服务器，通过HTTP访问
  • 适合团队共享、企业API集成
  • 配置示例："type": "remote"

第二步：配置文件结构

在opencode.jsonc中添加mcp配置项：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "服务器名称": {
      "type": "local 或 remote",
      "command": ["启动命令"],
      "enabled": true
    }
  }
}

第三步：配置本地MCP服务器

基础配置

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

带环境变量配置

{
  "mcp": {
    "my-server": {
      "type": "local",
      "command": ["python", "server.py"],
      "environment": {
        "API_KEY": "{env:MY_API_KEY}"
      }
    }
  }
}

第四步：配置远程MCP服务器

基础配置

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

带认证配置

{
  "mcp": {
    "my-remote-server": {
      "type": "remote",
      "url": "https://mcp.example.com",
      "headers": {
        "Authorization": "Bearer {env:API_KEY}"
      }
    }
  }
}

第五步：配置OAuth认证

自动OAuth（推荐）

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

手动触发认证

opencode mcp auth <服务器名称>

预注册客户端

{
  "mcp": {
    "oauth-server": {
      "type": "remote",
      "url": "https://mcp.example.com",
      "oauth": {
        "clientId": "{env:CLIENT_ID}",
        "clientSecret": "{env:CLIENT_SECRET}",
        "scope": "tools:read"
      }
    }
  }
}

禁用OAuth

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

第六步：管理MCP服务器

查看服务器列表

opencode mcp list

调试连接问题

opencode mcp debug <服务器名称>

移除认证

opencode mcp logout <服务器名称>

禁用特定服务器

{
  "tools": {
    "服务器名称": false
  }
}

使用通配符批量禁用

{
  "tools": {
    "mcp_*": false
  }
}

按代理启用

{
  "mcp": {
    "my-server": {
      "type": "local",
      "command": ["npx", "server"],
      "enabled": true
    }
  },
  "tools": {
    "my-server": false
  },
  "agent": {
    "my-agent": {
      "tools": {
        "my-server": true
      }
    }
  }
}

第七步：常用MCP服务器配置

Sentry（错误监控）

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

认证：opencode mcp auth sentry

Context7（文档搜索）

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

Grep by Vercel（代码搜索）

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

第八步：在提示词中使用

在提示词中添加相应指令：

Show me latest errors use sentry
Configure Nginx use context7
How to implement auth use gh_grep

或添加规则到AGENTS.md：

When searching docs, use context7
When searching code examples, use gh_grep

第九步：常见问题排查

问题1：认证失败

# 查看认证状态
opencode mcp auth list

# 调试连接
opencode mcp debug <服务器名称>

问题2：连接超时

{
  "mcp": {
    "slow-server": {
      "type": "remote",
      "url": "https://mcp.example.com",
      "timeout": 10000
    }
  }
}

问题3：工具不可用

  1. 检查服务器是否启用：opencode mcp list
  2. 确认提示词中使用了正确的服务器名称
  3. 查看OpenCode日志确认工具是否正确注册

问题4：本地服务器启动失败

  • 确认命令路径正确
  • 检查环境变量设置
  • 验证端口是否被占用
  • 确保有执行权限

第十步：配置选项速查表

本地服务器选项

| 选项 | 必需 | 描述 |
|------|------|------|
| type | 是 | 固定为"local" |
| command | 是 | 启动命令数组 |
| environment | 否 | 环境变量 |
| enabled | 否 | 是否启用 |
| timeout | 否 | 超时时间(毫秒) |

远程服务器选项

| 选项 | 必需 | 描述 |
|------|------|------|
| type | 是 | 固定为"remote" |
| url | 是 | 服务器URL |
| headers | 否 | HTTP请求头 |
| oauth | 否 | OAuth配置 |
| enabled | 否 | 是否启用 |
| timeout | 否 | 超时时间(毫秒) |

OAuth配置选项

| 选项 | 描述 |
|------|------|
| clientId | OAuth客户端ID |
| clientSecret | OAuth客户端密钥 |
| scope | 请求范围 |

注意事项

  1. 上下文限制：MCP工具会占用上下文空间，避免同时启用过多服务器
  2. 安全第一：使用环境变量存储敏感信息，不要硬编码
  3. 性能考虑：优先使用本地服务器减少网络延迟
  4. 团队协作：在AGENTS.md中记录推荐的MCP配置

快速参考命令

# 查看所有MCP服务器
opencode mcp list

# 认证服务器
opencode mcp auth <名称>

# 调试问题
opencode mcp debug <名称>

# 移除认证
opencode mcp logout <名称>
OpenCode