> ## Documentation Index
> Fetch the complete documentation index at: https://schaltwerk.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Integration

> Automate session management with the Model Context Protocol REST API

Schaltwerk ships with a Model Context Protocol (MCP) server so AI assistants (Claude, Codex, OpenCode, Factory Droid, etc.) can automate session management.

<Info>
  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.
</Info>

## Setup

### Option 1: Via Schaltwerk Settings (Recommended)

<Steps>
  <Step title="Open Settings">
    Click the gear icon in the top bar to open Schaltwerk Settings
  </Step>

  <Step title="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.
  </Step>

  <Step title="Restart Agent">
    Restart your orchestrator session to load the MCP configuration
  </Step>
</Steps>

### Option 2: Manual Setup

If you prefer manual setup or your agent doesn't appear in settings:

<Tabs>
  <Tab title="Codex">
    ```bash theme={null}
    # 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).
  </Tab>

  <Tab title="Claude Code">
    ```bash theme={null}
    claude mcp add --transport stdio --scope project schaltwerk \
      node /absolute/path/to/schaltwerk/mcp-server/build/schaltwerk-mcp-server.js
    ```

    Restart Claude Code to load the MCP server. Rebuild only if you modified the source.
  </Tab>

  <Tab title="Factory Droid">
    ```bash theme={null}
    droid mcp add --transport stdio --scope project schaltwerk \
      node /absolute/path/to/schaltwerk/mcp-server/build/schaltwerk-mcp-server.js
    ```

    Restart Factory Droid to load the MCP server. Rebuild is optional unless you changed the code.
  </Tab>

  <Tab title="Manual Config">
    Add to your agent's MCP configuration file:

    **For Codex** (`~/.codex/config.json`):

    ```json theme={null}
    {
      "mcpServers": {
        "schaltwerk": {
          "command": "node",
          "args": ["/absolute/path/to/schaltwerk/mcp-server/build/schaltwerk-mcp-server.js"]
        }
      }
    }
    ```

    **For Claude Code** (`.claude.json` in project root):

    ```json theme={null}
    {
      "mcpServers": {
        "schaltwerk": {
          "type": "stdio",
          "command": "node",
          "args": ["/absolute/path/to/schaltwerk/mcp-server/build/schaltwerk-mcp-server.js"]
        }
      }
    }
    ```
  </Tab>
</Tabs>

## What Can Agents Do?

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

<CardGroup cols={2}>
  <Card title="Create Sessions" icon="plus">
    Agent can create new specs or sessions directly in Schaltwerk
  </Card>

  <Card title="Update Specs" icon="pen">
    Modify existing spec content before starting work
  </Card>

  <Card title="Start Work" icon="play">
    Convert specs to running sessions with worktrees
  </Card>

  <Card title="Check Status" icon="list">
    Query all sessions and their current state
  </Card>

  <Card title="Open PR Modal" icon="code-compare">
    Agent can request opening the Create PR dialog (you review and confirm in the UI)
  </Card>

  <Card title="Setup Scripts" icon="bolt">
    Read the current worktree setup script, then propose and apply updates after confirming which untracked config (e.g., .env) should be copied.
  </Card>
</CardGroup>

## 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)

```json theme={null}
{
  "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:

```text theme={null}
GET /api/specs/summary
```

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

```text theme={null}
GET /api/specs/{session_id}
```

```json theme={null}
{
  "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

<Steps>
  <Step title="Agent receives task">
    You give your agent a coding task
  </Step>

  <Step title="Agent creates session">
    Agent uses MCP to create a Schaltwerk session with the task description
  </Step>

  <Step title="Schaltwerk updates">
    New session appears in your sidebar automatically
  </Step>

  <Step title="You review">
    Check the session, test the code, and merge when ready
  </Step>
</Steps>

## Use Cases

<AccordionGroup>
  <Accordion title="Task Breakdown">
    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
  </Accordion>

  <Accordion title="Code Review Automation">
    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
  </Accordion>

  <Accordion title="Multi-Agent Workflows">
    Coordinate multiple AI agents:

    * Orchestrator agent breaks down work
    * Creates sessions for implementation agents
    * Monitors progress across all sessions
    * Collects results when ready
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Sessions not appearing">
    Make sure Schaltwerk is running and your project is open. The MCP server only works when Schaltwerk is active.
  </Accordion>

  <Accordion title="Agent can't connect">
    Restart your agent after setting up MCP. The MCP tools are only loaded when the agent starts.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Prompting Guide" icon="message" href="/mcp/prompting">
    Learn how to write effective prompts
  </Card>

  <Card title="Agent Setup" icon="robot" href="/guides/agent-setup">
    Configure your agents
  </Card>
</CardGroup>