Skip to main content
Schaltwerk ships with a Model Context Protocol (MCP) server so AI assistants (Claude, Codex, OpenCode, Factory Droid, etc.) can automate session management.
The MCP server binary is bundled with the app—most users simply enable it in Settings. Node.js is only required if you intend to rebuild the server source.

​
Setup

1

Open Settings

Click the gear icon in the top bar to open Schaltwerk Settings
2

Configure MCP

Go to Agent Configuration, select your agent (Claude Code, Codex, OpenCode, or Gemini), and toggle Enable MCP. Schaltwerk writes the necessary config pointing to the embedded server.
3

Restart Agent

Restart your orchestrator session to load the MCP configuration

​
Option 2: Manual Setup

If you prefer manual setup or your agent doesn’t appear in settings: 
# Register Codex with the bundled MCP server (rebuild optional)
codex mcp add schaltwerk node /absolute/path/to/schaltwerk/mcp-server/build/schaltwerk-mcp-server.js
Restart Codex to load the MCP server. If you changed the MCP source, rebuild it first (see the development appendix).

​
What Can Agents Do?

Once set up, your AI agent can use these MCP tools to automate session management:

Create Sessions

Agent can create new specs or sessions directly in Schaltwerk

Update Specs

Modify existing spec content before starting work

Start Work

Convert specs to running sessions with worktrees

Check Status

Query all sessions and their current state

Open PR Modal

Agent can request opening the Create PR dialog (you review and confirm in the UI)

Setup Scripts

Read the current worktree setup script, then propose and apply updates after confirming which untracked config (e.g., .env) should be copied.

​
Pull Requests via MCP

Agents can request that Schaltwerk open the Create Pull Request dialog for a running/reviewed session:
  • Tool: schaltwerk_create_pr
  • Result: Schaltwerk opens the PR modal with suggested values
  • You still confirm the PR in the UI (the tool does not create the PR directly)
{
  "session_name": "my-session",
  "pr_title": "Add caching to search endpoint",
  "pr_body": "Summary…",
  "base_branch": "main",
  "pr_branch_name": "pr/my-session",
  "mode": "squash"
}

​
Worktree Setup Scripts via MCP

  • Read first: Call schaltwerk_get_setup_script to load the existing script.
  • Inspect & confirm: Check the repo for untracked config (e.g., .env, .env.local, .npmrc) and confirm with the user which files should be copied into new worktrees.
  • Write full script: Send the complete updated script (with shebang) via schaltwerk_set_setup_script. The script runs once per new worktree with WORKTREE_PATH, REPO_PATH, SESSION_NAME, and BRANCH_NAME env vars.
  • UI safeguard: When edited in the app, Schaltwerk prompts before saving. MCP changes rely on the agent following the read/confirm/write flow above.

​
Spec Discovery API

Agents can inspect specs without crawling the full session list. Use the following MCP tools when you need to review planning docs before starting work:
  • schaltwerk_spec_list — returns an array of spec summaries { session_id, display_name?, content_length, updated_at }
  • schaltwerk_spec_read — fetches the full markdown plus metadata for a given spec
Developing against the REST API directly? The MCP bridge proxies two lightweight endpoints: 
GET /api/specs/summary

{
  "specs": [
    {
      "session_id": "auth-registration",
      "display_name": "Auth Registration",
      "content_length": 1824,
      "updated_at": "2025-01-12T10:42:03Z"
    }
  ]
}

GET /api/specs/{session_id}

{
  "session_id": "auth-registration",
  "display_name": "Auth Registration",
  "content": "# Spec…",
  "content_length": 1824,
  "updated_at": "2025-01-12T10:42:03Z"
}
Both endpoints diff against the same backing data the desktop app uses, so you always see the latest spec content without hitting git. Response sizes are bounded by the spec markdown itself; content_length is counted in Unicode code points so agents can paginate or highlight accurately.

​
How It Works

1

Agent receives task

You give your agent a coding task
2

Agent creates session

Agent uses MCP to create a Schaltwerk session with the task description
3

Schaltwerk updates

New session appears in your sidebar automatically
4

You review

Check the session, test the code, and merge when ready

​
Use Cases

Break down a large feature into multiple parallel sessions:
  • Agent creates multiple specs for different components
  • Each spec becomes a separate session
  • Work on all parts simultaneously
  • Review and merge independently
Let your agent help with code reviews:
  • Agent analyzes pull requests
  • Creates Schaltwerk session with review notes
  • You see the session appear in sidebar
  • Review agent’s feedback and suggestions
Coordinate multiple AI agents:
  • Orchestrator agent breaks down work
  • Creates sessions for implementation agents
  • Monitors progress across all sessions
  • Collects results when ready

​
Troubleshooting

Make sure Schaltwerk is running and your project is open. The MCP server only works when Schaltwerk is active.
Restart your agent after setting up MCP. The MCP tools are only loaded when the agent starts.

​
Next Steps

Prompting Guide

Learn how to write effective prompts

Agent Setup

Configure your agents