MCP server reference
Transports, environment variables, per-client registration snippets, and the per-connection pin isolation contract for trw-mcp. Reference tables only — linked pages explain the reasoning.
Transport modes
trw-mcp supports three FastMCP transports. User projects run per-instance stdio. The TRW dev repo runs a shared streamable-HTTP server on loopback so multiple clients share one process.
| Transport | When to use | Address | Lifecycle |
|---|---|---|---|
| stdio | Default for user projects. One MCP process per CLI session. | (pipe) | Spawned and terminated by the MCP client. |
| streamable-http | This dev repo only. One server shared by Claude Code proxy, opencode, and other clients. | http://127.0.0.1:8100/mcp | Started via make mcp-server; stopped via make mcp-server-stop. |
| sse | Legacy server-sent-events fallback. Retained for compatibility with older clients. | http://host:port/sse | Long-lived HTTP connection; restart on crash. |
Transport resolution precedence: CLI flag --transport > TRW_MCP_TRANSPORT env var > .trw/config.yaml > default (stdio). Source: server/_transport.py.
Environment variables
Every .trw/config.yaml field is overridable by an environment variable with the TRW_ prefix (case-insensitive). The table below lists the runtime knobs most often set outside the config file.
| Variable | What it does | Default | Example |
|---|---|---|---|
| TRW_SESSION_ID | Stable per-connection identity for pin isolation. Set it to make pins survive reconnects of the same logical session. | unset (ctx.session_id) | claude-code-main |
| ENABLE_TOOL_SEARCH | Force-enable or force-disable the deferred tool-search layer. Default is auto: enable when tool descriptions exceed 10% of the context window. | auto | false |
| CLAUDE_CODE_SUBAGENT_MODEL | Model shortname spawned for Task subagents. Accepted values match Claude Code shortnames (opus, sonnet, haiku). | sonnet | opus |
| CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS | Gate for Agent Teams. Required (value 1) for TeamCreate/SendMessage/ TaskCreate; without it those tools silently no-op. | unset | 1 |
| TRW_MCP_TRANSPORT | Override the transport without editing config. One of stdio, sse, streamable-http. | stdio | streamable-http |
| TRW_MCP_PORT | Bind port for HTTP transports. | 8100 | 8181 |
Full list: models/config/_main_fields.py (every field accepts TRW_<UPPER>). Run trw-mcp config-reference locally for the generated list.
MCP config snippets
Each supported CLI registers trw-mcp in its own config surface. The installer writes these for you; the snippets below document the shape so you can inspect or hand-edit. Pick your client:
Your client
// .mcp.json (repo root)
{
"mcpServers": {
"trw": {
"command": "trw-mcp",
"args": []
}
}
}Installer hook
The installer (install.sh → install-trw.py) registers trw-mcp once per selected client profile. Each profile declares its own surface paths, and the installer writes the MCP entry using the shape above.
| Profile | MCP config surface | Instruction surface |
|---|---|---|
| Claude Code | .mcp.json | CLAUDE.md, .claude/ |
| Cursor IDE | .cursor/mcp.json | .cursor/rules/ |
| Cursor CLI | .cursor/mcp.json | AGENTS.md, .cursor/cli.json |
| OpenCode | opencode.json | .opencode/INSTRUCTIONS.md |
| Codex CLI | .codex/config.toml | .codex/INSTRUCTIONS.md |
| GitHub Copilot CLI | .github/copilot/mcp.json | .github/copilot-instructions.md |
| Gemini CLI | .gemini/settings.json | GEMINI.md |
| Aider | — (instruction-only) | AGENTS.md, .aider/ |
Profile definitions: platform/src/lib/docs/client-profiles.ts (UI-facing) and trw-mcp/src/trw_mcp/models/config/_profiles.py (runtime).
Troubleshooting
Four failure modes come up often enough to list here. Deeper diagnosis lives on the troubleshooting page.
| Symptom | Cause | Fix |
|---|---|---|
[Errno 2] No such file or directory on trw_* tool calls | MCP server process died. | Type /mcp in the client to reconnect. |
| Tool changes not picked up | Server loads code at startup; edits to trw-mcp/src/ require a restart. | /mcp to restart, or make mcp-server-stop && make mcp-server. |
| Pins from old session still active | Boot-time sweep retires stale active runs. Disabled pins carry over when TRW_SESSION_ID matches. | Delete .trw/runtime/pins.json, or rotate TRW_SESSION_ID. |
| Tool descriptions exceed context window | 24+ tools can auto-defer at >10% of context. Affects older clients. | Set ENABLE_TOOL_SEARCH=true, or switch to tool_exposure_mode: core. |
Pin isolation runbook: docs/documentation/operational-knowledge/pin-isolation-migration.md.
Related pages