ADR-0065: One-Command MCP Client Configuration¶

Status: Accepted
Date: 2026-04-18
Context: Connecting a Trails app to an MCP client (Claude Desktop, Cursor, etc.) requires manually editing JSON config files, looking up the correct paths per OS, and restarting the client. This is error-prone and discourages adoption.

Decision¶

Add a trails mcp subcommand group that automates MCP client configuration:

Command	Purpose
`trails mcp install --claude`	Add project to Claude Desktop config
`trails mcp install --cursor`	Add project to Cursor MCP config
`trails mcp install --custom FILE`	Write entry to any config file
`trails mcp status`	Show registration status across clients
`trails mcp uninstall --claude`	Remove project entry from Claude Desktop
`trails mcp test`	Smoke-test the MCP server (tools/list, resources/list)

Config file locations¶

Client	macOS	Linux	Windows
Claude Desktop	`~/Library/Application Support/Claude/claude_desktop_config.json`	`~/.config/claude/claude_desktop_config.json`	`%APPDATA%/Claude/claude_desktop_config.json`
Cursor	`{project}/.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global)	same	same

Config entry shape¶

{
  "mcpServers": {
    "trails-{project_name}": {
      "command": "trails",
      "args": ["server", "--transport", "stdio"],
      "cwd": "/absolute/path/to/project"
    }
  }
}

Safety invariants¶

Never overwrite non-trails entries. Only add/update keys matching trails-* in mcpServers.
Idempotent. Running install twice updates the entry, never duplicates it.
Graceful creation. Missing directories and files are created as needed.

Entry point¶

A trails-mcp script entry point is added to pyproject.toml as a shortcut for trails server --transport stdio, reducing the config to:

{"command": "trails-mcp", "cwd": "/path/to/project"}

Consequences¶

Users can go from trails new myapp to a working Claude Desktop integration in one command.
The trails mcp test command provides a quick sanity check without opening the client.
Future MCP clients can be supported by adding detection logic to mcp_install.py without changing the user-facing interface.