AgentSkillsCN

mcp-arch

解释MCP如何在OpenWork、OpenCode与OpenWork服务器之间进行连接，并指导配置或身份验证方面的故障排除。 当用户提及以下内容时触发： - “MCP连接” - “MCP架构” - “MCP配置”

SKILL.md
--- frontmatter
name: mcp-arch
description: |
  Explain how MCP is wired between OpenWork, OpenCode, and the OpenWork server, and guide config or auth troubleshooting.

  Triggers when user mentions:
  - "mcp wiring"
  - "mcp architecture"
  - "mcp config"

Quick Usage (Already Configured)

Provide wiring overview

  • •OpenWork UI uses the OpenCode SDK for runtime MCP calls and events.
  • •MCP config lives in opencode.json under mcp; OpenWork server only reads/writes config for remote clients.
  • •MCP auth tokens are managed by OpenCode and stored outside the repo.
  • •Remote UI traffic hits the OpenWork server at /opencode/*, which proxies to OpenCode.
  • •The OpenWork server must include the workspace directory (via x-opencode-directory or directory query) so OpenCode loads the correct config.

Troubleshoot auth errors

  • •Confirm the MCP entry type and required fields (local needs command[], remote needs url).
  • •If refresh tokens are invalid, re-auth via OpenCode and reload the engine after config edits.
  • •Avoid editing token files directly; use OpenCode commands or endpoints.
  • •If the UI says "does not support OAuth", verify the directory matches the on-disk opencode.json path.
  • •In remote mode, OpenWork approval gates apply for mcp.add and engine.reload unless auto-approve is explicitly enabled.

Common Gotchas

  • •Engine reload only re-reads config; it does not refresh OAuth tokens.
  • •Remote clients need OpenWork server for config writes, but MCP runtime still routes through OpenCode.
  • •macOS can resolve temp paths as /private/tmp/... while config is under /tmp/...; normalize before calling MCP endpoints.

First-Time Setup (If Not Configured)

  1. •Add the MCP entry to opencode.json.
  2. •Restart or reload the OpenCode engine.
  3. •Authenticate the MCP provider via OpenCode.