> ## 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 Server Setup

> Enable the bundled Schaltwerk MCP server so AI agents can manage sessions

Schaltwerk ships with a prebuilt Model Context Protocol (MCP) server. In most cases you only need to **toggle it on in Settings** so your AI agent (Claude Code, Codex, OpenCode, or Gemini) can control sessions. Node.js is **not required** unless you plan to rebuild the server from source.

<Info>
  MCP automation works while Schaltwerk is running and the project is open. Make sure the relevant agent CLI (Claude Code, Codex, OpenCode, or Gemini) is installed and authenticated before enabling MCP.
</Info>

## Enable the Bundled MCP Server (Recommended)

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

  <Step title="Select Agent Configuration">
    In the left sidebar choose **Agent Configuration**, then pick the agent you want to automate (Claude Code, Codex, OpenCode, or Gemini).
  </Step>

  <Step title="Enable the MCP toggle">
    In the **MCP Server Configuration** panel, turn on **Enable MCP**. Schaltwerk writes the necessary `.mcp.json` entry using the embedded server binary.

    * If the agent CLI is missing, install it first (for example `brew install claude-code`).
    * When the toggle succeeds you’ll see the server status marked as **📦 Embedded** and configuration **✅ Configured**.
  </Step>

  <Step title="Restart the agent">
    Restart your orchestrator terminal or the external agent CLI so it loads the new MCP configuration.
  </Step>

  <Step title="Verify">
    In your agent (e.g., Claude Code) run a query such as “List my Schaltwerk sessions.” You should see the active sessions from this project.
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="CLI not detected">
    **Symptom:** MCP panel shows ⚠️ Not found for the agent CLI.

    **Fix:** Install the CLI and restart Settings: `brew install claude-code`, `npm install -g @statelyai/stately-cli` (Codex), etc.
  </Accordion>

  <Accordion title="Agent still says MCP server missing">
    **Symptom:** After enabling, the agent reports “no MCP servers configured.”

    **Fix:**

    1. Disable and re-enable the MCP toggle.
    2. Restart the agent CLI (e.g., `claude --reset` or relaunch Codex).
    3. In Settings, click the reset button in the orchestrator terminal to reload configuration.
  </Accordion>

  <Accordion title="Need to remove MCP configuration">
    Turn off the **Enable MCP** toggle. Schaltwerk removes the entry from `.mcp.json` (or the agent’s global config).
  </Accordion>
</AccordionGroup>

## Available Tools

Once MCP is enabled, agents can call these tools:

<CardGroup cols={2}>
  <Card title="Create Sessions" icon="plus">
    `schaltwerk_create` — Create new specs or running sessions
  </Card>

  <Card title="List Sessions" icon="list">
    `schaltwerk_list` — Retrieve sessions with status info
  </Card>

  <Card title="Browse Specs" icon="document">
    `schaltwerk_spec_list` — See spec names, sizes, and timestamps<br />
    `schaltwerk_spec_read` — Fetch full markdown for a single spec
  </Card>

  <Card title="Cancel Sessions" icon="trash">
    `schaltwerk_cancel` — Remove sessions after they merge (deletes worktree & branch; spec moves to Archives)
  </Card>

  <Card title="Setup Scripts" icon="bolt">
    `schaltwerk_get_setup_script` to read the current worktree bootstrap script, `schaltwerk_set_setup_script` to replace it after confirming which untracked config to copy.
  </Card>
</CardGroup>

<Tip>
  Unsure what a tool does? Ask your agent to show the MCP documentation, or inspect the source in `mcp-server/src/tools`.
</Tip>

## Security & Safety

<Warning>
  The MCP server can create, modify, and delete git worktrees. Only enable it for agents you trust and keep your project under version control.
</Warning>

**Critical Rules:**

* ✅ Canceling after merge is routine cleanup—it deletes the session worktree/branch and reclaims disk while keeping the spec in Archives
* ❌ Canceling before merge or without tests risks losing uncommitted work; use `schaltwerk_pause` if you’re unsure
* ⚠️ `schaltwerk_cancel` (and the UI’s cancel action) removes the session worktree & branch immediately. Any uncommitted changes vanish. The spec content is archived in **Settings → Archives** for recovery.

***

Looking to automate more workflows? Continue with [MCP Integration](/mcp/integration) to see what agents can do once the server is active.