Skip to main content
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.
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.
1

Open Settings

Click the gear icon in the top bar to open the Settings modal.
2

Select Agent Configuration

In the left sidebar choose Agent Configuration, then pick the agent you want to automate (Claude Code, Codex, OpenCode, or Gemini).
3

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.
4

Restart the agent

Restart your orchestrator terminal or the external agent CLI so it loads the new MCP configuration.
5

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.

​
Troubleshooting

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.
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.
Turn off the Enable MCP toggle. Schaltwerk removes the entry from .mcp.json (or the agent’s global config).

​
Available Tools

Once MCP is enabled, agents can call these tools:

Create Sessions

schaltwerk_create — Create new specs or running sessions

List Sessions

schaltwerk_list — Retrieve sessions with status info

Browse Specs

schaltwerk_spec_list — See spec names, sizes, and timestamps
schaltwerk_spec_read — Fetch full markdown for a single spec

Cancel Sessions

schaltwerk_cancel — Remove sessions after they merge (deletes worktree & branch; spec moves to Archives)
Unsure what a tool does? Ask your agent to show the MCP documentation, or inspect the source in mcp-server/src/tools.

​
Security & Safety

The MCP server can create, modify, and delete git worktrees. Only enable it for agents you trust and keep your project under version control.
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 to see what agents can do once the server is active.