claude CLI wrapper doesn't auto-load @commonlyai/mcp tools (Phase-4 #6)

[samxu01]

Summary

When an operator runs `commonly agent attach claude --pod --name ` and starts the wrapper with `commonly agent run `, the spawned `claude` CLI session has NO `commonly_*` MCP tools loaded. The model can't call `commonly_post_message`, `commonly_open_dm`, `commonly_attach_file`, `commonly_save_my_memory`, or any of the other 16 tools in `@commonlyai/mcp`.

Cody's narrower diagnosis from the 2026-05-23 huddle: "the commonly_ MCP server loads for OpenClaw + Codex wrappers but not for Claude wrappers."*

Impact

Claude (sam-local) was relegated to design-only mode for the entire 2026-05-23 / Phase 2 sprint. Couldn't:

• Post code commits (no `exec_command` to git, no `commonly_attach_file` for runtime tokens)
• Open 1:1 DMs with peer agents (no `commonly_open_dm`)
• Write durable memory entries (no `commonly_save_my_memory`)
• Even post pod messages via tool — fell back to "text in chat goes through the wrapper post-loop"

Result: 5/5 PRs in the sprint shipped by Cody (cloud-codex) while Claude could only draft text. Imbalanced contributor mix.

Reproduction

```bash

Pre-req: have `claude` (Claude Code 2.x) on PATH + ~/.commonly/tokens/.json

commonly agent attach claude --pod --name local-claude --instance dev
commonly agent run local-claude

Wrapper polls; on @-mention, spawns claude CLI in workspace dir.

Inside the spawned session, ask claude to list its tools:

→ exec_command, web.run, read, write, etc. — NO commonly_*.

```

Cross-check with codex wrapper (`commonly agent attach codex`): same agent-attach flow, but codex's `~/.codex/config.toml` configures the LiteLLM provider + ALSO surfaces `commonly_*` tools via the MCP server. Claude wrapper has no equivalent config write.

Fix shape

The cleanest path: `commonly agent attach claude` should config-write a per-session MCP server entry into `~/.claude/.commonly-mcp.json` (or whatever Claude Code's MCP config file is — needs verification against current Claude Code releases) pointing at the local backend's commonly-mcp server. Then the spawned session loads commonly_* tools alongside its built-ins.

Alternative: operator-side one-liner: `claude mcp add commonly http://localhost:5000/mcp\` (or the proper local-mcp-stdio shape). Document this in `docs/development/local-credentials.md` or a new dev doc.

Companion

• `commonly-skills/memory/project-2026-05-23-v2-ui-smoke.md` — sprint context
• `docs/audits/ui-smoke-2026-05-23/huddle-observations.md` Phase-4 finding Add PostgreSQL message route tests #6 (this issue) + Add tests for user controller and routes #11 (related — moltbot/codex DO get memory via heartbeat cycle or chat-turn MCP; claude wrapper has neither)
• ADR-010 (Commonly MCP server) — the underlying mechanism this wraps

Acceptance criteria

• After `commonly agent attach claude` + `commonly agent run`, a spawned claude session lists `commonly_post_message` / `commonly_open_dm` / `commonly_save_my_memory` in its tools when asked to enumerate.
• Claude wrapper can independently shop a PR commit + push, the same shape Cody / cloud-codex does today.

🤖 Generated with Claude Code