Skip to main content
TRW
Skip to content
TRWMCP Server Reference

Runtime reference

MCP server reference

Understand what the host starts, which file the installer changes, which settings belong to trw-mcp, and how to recover without deleting shared project state.

stdio onlyhost-managed processrepo-aware state

Connection model

The client owns the process

trw-mcp supports stdio. A host starts a process for an MCP connection and decides when to restart it. “Per session” is not a portable lifecycle promise: different clients reuse, reconnect, or replace that process differently.

1

Host client

Reads its own MCP registration and starts the configured command.

2

stdio process

Exchanges MCP messages over stdin/stdout; no HTTP listener is opened.

3

Connection identity

Uses MCP context unless an operator explicitly supplies TRW_SESSION_ID.

4

Project state

Resolves config, runs, and memory from the repository the process serves.

Transport implementation: server/_transport.py. Registration and state identity are separate concerns.

Runtime controls

Separate server settings from host settings

trw-mcp configuration fields accept TRW_<FIELD_NAME> overrides. Host clients also define environment variables of their own; those variables do not become server configuration just because the client launches trw-mcp.

TRW_SESSION_IDInspect
Owner
Server process
Purpose
Overrides connection identity when an operator needs a stable explicit pin scope
Default
MCP context identity, then process UUID fallback
TRW_CONFIG_STRICTInspect
Owner
Server process
Purpose
Fails closed instead of falling back when configuration validation fails
Default
off
TRW_PLATFORM_API_KEYInspect
Owner
Server process
Purpose
Authenticates the optional hosted backend; keep it out of config.yaml
Default
unset
ENABLE_TOOL_SEARCHInspect
Owner
Host client
Purpose
Controls deferred tool discovery in clients that implement that setting
Default
host-specific
CLAUDE_CODE_SUBAGENT_MODELInspect
Owner
Host client
Purpose
Selects a Claude Code subagent model; it is not a trw-mcp server setting
Default
host-specific

Configuration shapes

Inspect the merge; do not paste blindly

These examples explain each client’s document shape. They are intentionally not described as byte-for-byte installer output: writers may resolve an executable path, add arguments, or preserve an existing customized entry.

Configuration family

// .mcp.json — illustrative shape
{
  "mcpServers": {
    "trw": { "command": "trw-mcp", "args": [] }
  }
}

Client registration

One server, client-specific surfaces

A selectable target profile is not the same as a dedicated MCP writer. Current bootstrap source smart-merges supported client files rather than replacing the user’s entire document; a published installer can lag that source.

Claude CodeInspect
MCP surface
.mcp.json
Current integration behavior
Merges the trw entry and preserves other MCP servers
Cursor IDE / CLIInspect
MCP surface
.cursor/mcp.json
Current integration behavior
Both Cursor profiles share one repo-scoped MCP surface
OpenCodeInspect
MCP surface
opencode.json
Current integration behavior
Merges mcp.trw into the existing OpenCode document
Codex CLIInspect
MCP surface
.codex/config.toml
Current integration behavior
Merges mcp_servers.trw and preserves user-managed entries
Antigravity CLIInspect
MCP surface
.antigravitycli/settings.json
Current integration behavior
Merges mcpServers.trw while preserving existing Antigravity settings
GitHub Copilot CLIInspect
MCP surface
.mcp.json
Current integration behavior
The shared root scaffold registers trw in the project-level CLI format
AiderInspect
MCP surface
None — retired 2026-07-11
Current integration behavior
Retired. The installer rejects --ide aider with a retirement notice; the identifier is kept only for uninstall and migration cleanup.

Runtime registry and writers: src/trw_mcp/bootstrap/. Inspect the generated file after installation; do not infer support from a profile name alone.

Recovery

Inspect before changing state

Client reconnect commands are not universal. Start with the executable, client log, and reported TRW identity; then make the smallest scoped correction.

01

The client cannot start trw-mcp

Inspect

Run trw-mcp --help in the same environment and inspect that client’s MCP log

Then

Repair the command or PATH, then restart the MCP connection using the client’s own UI or command

02

A code change is not visible

Inspect

Confirm which executable or Python module the client registration launches

Then

Restart that client-managed process; reconnect commands differ by client

03

The active run or pin is unexpected

Inspect

Use trw_status and compare the reported session/run identity before changing state

Then

Adopt the intended run explicitly or start a new logical session; do not delete the shared pin store

04

Too many tool schemas are exposed

Inspect

Check tool_resolution_mode and the active run task_type that selects the capability packs

Then

Keep tool_resolution_mode at standard (kernel + per-task packs) in .trw/config.yaml; set it to all only as a deliberate operator escape, and use trw_request_tool_access for a single masked tool

TroubleshootingCLI flags

Next

See how the MCP server lands in a real client install.

The Claude Code guide walks the full install end to end. Configuration covers the knobs the installer reads from .trw/config.yaml.

Install walkthroughConfig reference