mcp-state-sidecar — Claude Code MCP server: durable agent state
Keeps multi-agent workflow state outside the agents, so keys, workflows, leases and history survive a crashed process.
claude mcp add mcp-state-sidecar -- uvx mcp-state-sidecarWhat mcp-state-sidecar does
State kept inside an agent dies with the process, and horizontal scaling or a framework switch makes it worse. mcp-state-sidecar takes a different route: agents read and write through the same tool calls they already use for any MCP server. Five tool groups ship with it. Key-Value Store (state_set, state_get, state_delete, state_list) with optional TTL. Workflow Lifecycle (workflow_create, workflow_claim, workflow_checkpoint, workflow_resume, workflow_status, workflow_discover, workflow_list) for coordinating distributed workers. Leases (lease_acquire, lease_release, lease_renew), sessions and history (session_save, session_restore, history_log), plus observability (sidecar_health, sidecar_reset).
Two run modes. HTTP SSE suits distributed setups: mcp-state-sidecar-http binds 0.0.0.0 on port 8000, with the endpoint at http://localhost:8000/mcp. Stdio runs it as a local subprocess via mcp-state-sidecar. Everything is configured through environment variables: STATE_BACKEND (sqlite or redis), DB_PATH, REDIS_URL, SIDECAR_HOST, SIDECAR_PORT.
SQLite with WAL mode and serialisation is the default backend; Redis handles higher concurrency. Redis needs the extra install, pip install mcp-state-sidecar[redis], otherwise that backend will not start. And sidecar_reset wipes every record irreversibly, so keep it away from anything you still need.
What it helps with
- persist workflow state across agent restarts
- claim a workflow atomically so two workers do not grab the same run
- resume a run from its last checkpoint after a crash
- hand an agent an exclusive lock on a resource with a TTL
- read the state-transition history with writer IDs
Example prompts for the agent
- Create a workflow tagged
ingestand show me therun_id - Claim that
run_idforworker-3and checkpoint step 2 - Save context for session
session-42, then restore it
How to install mcp-state-sidecar
Platform CLI
claude mcp add mcp-state-sidecar -- uvx mcp-state-sidecaruvx runs the command named after the package; if the README names another one, use uvx --from mcp-state-sidecar <command>
Platform CLI
codex mcp add mcp-state-sidecar -- uvx mcp-state-sidecaruvx runs the command named after the package; if the README names another one, use uvx --from mcp-state-sidecar <command>
Config file
{
"mcpServers": {
"mcp-state-sidecar": {
"command": "uvx",
"args": [
"mcp-state-sidecar"
]
}
}
}uvx runs the command named after the package; if the README names another one, use uvx --from mcp-state-sidecar <command>
Config file
{
"servers": {
"mcp-state-sidecar": {
"type": "stdio",
"command": "uvx",
"args": [
"mcp-state-sidecar"
]
}
}
}uvx runs the command named after the package; if the README names another one, use uvx --from mcp-state-sidecar <command>
Platform CLI
gemini mcp add mcp-state-sidecar uvx mcp-state-sidecaruvx runs the command named after the package; if the README names another one, use uvx --from mcp-state-sidecar <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about mcp-state-sidecar
How do I install mcp-state-sidecar in Claude Code?
Run claude mcp add mcp-state-sidecar -- uvx mcp-state-sidecar. The package is fetched by uvx, so no separate install step is needed.
What does mcp-state-sidecar do?
It is an MCP server that stores state for multi-agent workflows: TTL key-value entries, a workflow registry with claims and checkpoints, leases for locking, session snapshots and a transition log.
Which storage backends does it support?
SQLite with WAL mode and Redis for high concurrency. Redis requires the extra install: pip install mcp-state-sidecar[redis].
