1. 为什么你的 OpenCode 接上 MCP 后总是报错OpenCode 是一个开源的终端 AI 编程助手它最大的特点是支持通过 MCP 协议挂载外部工具让模型在对话中直接调用你本机或远程的能力。适合谁用适合那些已经写好 MCP Server、想让它在真实 AI 工作流里跑起来的开发者。但很多人卡在同一个地方命令行里python3 mcp_server.py跑得好好的一写进opencode.json就报ModuleNotFoundError、Connection refused或者Schema validation error。我试过把同一个工单分析 Server 分别用 local 和 remote 两种方式接入踩过的坑基本集中在四个环节启动、握手、调用、协议。这四个环节的报错信息长得完全不一样但排查路径其实可以整理成一张对照表。这篇文章就围绕opencode.json这份配置文件把 MCP 挂载、逐项验证、常见报错定位全部走一遍。你跟着做能独立完成接入也能在出问题时快速知道该看哪一行日志。核心检索词先明确OpenCode 的 MCP 配置写在~/.config/opencode/opencode.json以mcp字段为根每个 Server 用唯一名字标识type取local或remote。搞懂这四个字段接入就完成了一半。2. TaoToken 前置准备Base URL、Key 与 Model ID 三件套在写opencode.json之前得先把模型侧的东西准备好。OpenCode 本身不绑定某一家模型它通过 OpenAI 兼容接口去调用。这里我用 TaoToken 作为模型接入层因为它同时提供对话、Coding Plan 和 API Key 管理配置起来比较直接。你需要准备三样东西我把它叫做三件套第一Base URL。API 调用地址是https://taotoken.net/api注意这个地址后面不加任何 UTM 参数直接填进配置即可。如果你用的是 Claude Code 这类走 Anthropic 协议的工具接入端点会不一样具体看文档里的说明。第二API Key。去控制台的 API Keys 页面生成一个格式通常是一串以sk-开头的字符串。生成后立刻复制保存页面刷新后就看不到了。第三Model ID。这个取决于你想用哪个模型。在模型对话页面可以先试一下确认模型能正常响应再把对应的 Model ID 填进配置。常见的比如claude-sonnet-4-20250514这类标识具体以你账号下可用的为准。把这三件套准备好之后OpenCode 的模型侧就通了。接下来才是 MCP 的挂载。这里要提醒一句模型接入和 MCP 接入是两条独立的链路模型不通会导致对话没反应MCP 不通会导致工具调不到排查时要分开看。如果你还没生成 Key可以直接去 API Keys 页面操作想先验证模型是否可用去模型对话页面发一条消息试试如果是长期做编码和 Agent 任务Coding Plan 会更划算一些。这三个入口我都放在文末的 CTA 里了按需取用。3. 可复制的 opencode.json 配置local 与 remote 双形态这一节是全文的核心直接给可复制的配置片段。OpenCode 的配置文件路径是~/.config/opencode/opencode.json如果目录不存在就手动创建。先看 local 形态也就是 stdio 模式。OpenCode 启动时会作为父进程拉起 Server 子进程{ $schema: https://opencode.ai/config.json, mcp: { tickets_server: { type: local, command: [ /Users/yourname/repo/venv/bin/python3, /Users/yourname/repo/agent-mcp-demo/mcp_server.py ], enabled: true } } }四个字段各司其职。type取local表示走 stdiocommand是数组形式首元素是可执行程序、后续是参数数组比单字符串更安全能避免空格转义问题enabled是开关设为false可以临时禁用而不删配置开发期对照不同 Server 时特别有用。注意command里我写的是venv/bin/python3的绝对路径不是裸的python3。这是踩过坑之后的写法OpenCode 启动子进程时不会继承你终端的 venv 激活状态如果写python3它会用系统默认解释器依赖装在 venv 里就会报ModuleNotFoundError。再看 remote 形态对应 HTTP/SSE 传输{ mcp: { tickets_server_http: { type: remote, url: http://localhost:8000/mcp, enabled: true } } }remote 用url字段指向 HTTP 端点OpenCode 不会拉起任何进程直接尝试连接。这就要求 Server 必须已经独立运行否则握手阶段就会报错。两种类型可以混用。同一份配置里本机代码搜索工具走 local公司内网工单服务走 remote模型在对话中不区分 Tool 来自哪种传输统一按能力清单调用。选型逻辑很简单工具依赖本机环境、希望跟随 OpenCode 启停用 local工具部署在远程、团队共享、需要长期运行用 remote。如果你用的是 Cline MCP 或 Claude Code 的配置字段名会不同但三件套逻辑一致Base URL、Key、Model ID 都要写全。CC Switch 这类切换工具也是同理切换的是模型侧MCP 侧仍按上面的结构写。4. 逐项验证从握手到工具调用的成功结果配置写完不代表通了得逐项验证。我习惯按启动、握手、调用三步走每一步都有明确的成功标志。第一步验证 Server 能独立启动。在终端直接跑/Users/yourname/repo/venv/bin/python3 /Users/yourname/repo/agent-mcp-demo/mcp_server.py如果 Server 正常你会看到它打印启动日志并阻塞等待输入。这一步能过说明解释器路径和脚本本身没问题。如果报ModuleNotFoundError就是解释器选错了如果报语法错误看 traceback 定位行号。第二步验证 OpenCode 能握手。启动 OpenCode观察日志面板。local 模式下OpenCode 会拉起子进程并读取tools/list、resources/list、prompts/list三份能力清单。成功时你能在日志里看到 Server 名字和它暴露的工具数量。remote 模式下先用 curl 测连通性curl -v http://localhost:8000/mcp正常应返回 HTTP 状态码或 SSE 流头部。返回Connection refused说明 TCP 都没建立Server 没起或端口不对。第三步验证工具真能被调用。在 OpenCode 对话里发一条会触发工具的消息比如「帮我查一下工单 T-1001 的详情」。如果模型判断需要调用get_ticket_detail你会在日志里看到 Tool 调用请求和返回结果。成功标志是结果回填到对话里模型基于结果继续回答。这三步走完整条链路就通了。任何一步失败都能定位到具体环节而不是笼统地说「连不上」。5. 常见报错对照排查401、local proxy failed、reading choices、OAuth这一节把真实遇到的报错和排查路径列出来你可以直接对照。401 Unauthorized模型侧 Key 无效或没填。检查opencode.json里模型配置的 API Key 是否正确去 API Keys 页面确认 Key 还在有效期内。注意 Key 只在生成时显示一次丢了就重新生成。local proxy failed通常是 local 模式下子进程启动失败。回到第 4 节第一步用绝对路径在终端独立跑一遍 Server看 stderr 输出。九成是解释器路径或依赖问题。reading choices相关报错模型返回体解析失败多半是 Base URL 填错或模型不支持当前接口格式。确认 Base URL 是https://taotoken.net/apiModel ID 与账号下可用模型一致。可以去模型对话页面先验证模型能正常返回。OAuth相关报错如果你用的是需要 OAuth 的接入方式检查 token 是否过期。这类问题在 Claude Code 接入 Anthropic 协议时更常见配置里要写全 Base URL、Key、Model ID 三件套缺一不可。Schema validation errorTool 参数类型或必填项与调用不匹配。检查 Tool 的 docstring 和类型注解确保模型生成的参数符合 schema。JSON parse error报文格式错误启用 SDK 调试日志看原始报文。常见于 Server 端返回了非 JSON 内容比如 print 混进了 stdout。Protocol version mismatchClient 和 Server 的 SDK 版本不一致。把fastmcp和mcp包升级到一致版本。排查时记住一个原则Server 端有完整堆栈Client 端只有 error 响应。所以先看 Server 日志再看 OpenCode 日志面板。stdio 模式下 Server 的 print 会走到 stderr被 OpenCode 转发到日志面板HTTP 模式下日志在 Server 进程所在终端要单独看。6. 把 MCP 接入变成可复用的团队能力走到这里你已经能独立完成 OpenCode 的 MCP 接入和排错了。最后说几个实用技巧。第一Tool 内部一定要捕获异常。用try/except包住业务逻辑traceback.print_exc()留在异常分支里日志在 Server 端可见向 Client 返回的 error message 保持简洁不暴露内部栈信息。这样既保留排查依据又避免敏感信息进模型上下文。第二显式区分业务结果和技术异常。找不到工单是正常业务出口模型会基于这个信息继续推理数据库连接失败是技术异常模型应跳过或重试。这个区分 MCP 协议不强制但由 Tool 实现者主动维持影响很大。第三生产环境用 logging 模块替代 print。按级别写入文件或集中收集避免 print 散落各处难以排查。第四把 HTTP/SSE 版本的 Server 部署到内网在opencode.json里用type: remote接入整个团队共享同一个实例。再把团队沉淀的提示词封装成 Prompt 模板放进 ServerAgent 工作流就从个人工具变成了团队能力。需要生成 Key 或管理配额去 API Keys 页面想先验证模型是否可用去模型对话页面长期做编码和 Agent 任务Coding Plan 更合适。接入过程中遇到配置问题接入文档里有完整的字段说明。