cos: Skill for Claude Code

Debug a Cos MCP server in Cowork (and Claude Code)

The #1 source of confusion is mixing up two independent layers. Establish which one the user is hitting before doing anything — the diagnosis and the fix differ.

Layer	How the server runs	Config	Reads config…
Claude Cowork Desktop	Cowork spawns each server directly as a stdio command	~/Library/Application Support/Claude/claude_desktop_config.json	only at launch (⌘Q to reload)
Claude Code	a launchd supergateway bridge per server (:8001–:8006)	$REPO_ROOT/.mcp.json	per session (launchd supervises the bridge)

The board app (:3000) is a third, independent thing — it works with no bridges at all. Don't chase an MCP bug that's really "the board app isn't running on :3000" (see step 4).

Every shell block below starts with the loader so nothing is hardcoded:

source "$(git rev-parse --show-toplevel)/config/load-config.sh"

The full reference for this runbook is docs/reference/troubleshooting.md.

---

Step 0 — Scope it

Ask / confirm: which client (Cowork or Claude Code), which server (board / calendar / guard / vault / openwhispr / whatsapp), and what the user sees (missing from tools, "not responding", a tool call erroring, a specific error string). Then take the matching path below.

Step 1 — (Cowork) Relaunch first

Cowork reads claude_desktop_config.json only at launch and does not respawn a server that exited. After any config change, or any "it died" symptom, the first move is: fully quit Cowork (⌘Q — not just close the window) and reopen it. This alone resolves the majority of cases. Tell the user to do it and re-check before going deeper.

Confirm the server is even registered + the config is valid JSON (redact secrets):

source "$(git rev-parse --show-toplevel)/config/load-config.sh"
"$NODE_BIN" -e '
  const c = require(process.env.COWORK_CONFIG);
  const s = c.mcpServers || {};
  for (const [k, v] of Object.entries(s)) {
    const env = Object.fromEntries(Object.entries(v.env||{}).map(([ek,ev]) =>
      [ek, ek.includes("KEY") ? (ev?ev.slice(0,8)+"…":"EMPTY") : ev]));
    console.log(k, "->", v.command, JSON.stringify(v.args), JSON.stringify(env));
  }'

If a server is absent from mcpServers, or its command/args point at a stale/missing path (e.g. an old checkout), that's the bug — fix the entry (Step 5) and ⌘Q.