# MCP Arch

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

- Skill: `different-ai/mcp-arch` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add different-ai/mcp-arch`
- Raw SKILL.md: https://api.skillmd.com/api/skills/different-ai/mcp-arch/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: different-ai (https://skillmd.com/u/different-ai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/different-ai/mcp-arch

---


## 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.