# mcp-state-sidecar

Keeps multi-agent workflow state outside the agents, so keys, workflows, leases and history survive a crashed process.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 7
- Author: askadvaith
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/askadvaith/MCP-State-Sidecar
- Updated: 2026-06-12
- HTML: https://affpapa.org/en/nevibecode/mcp/mcp-state-sidecar

## What it 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.

## Requirements
- Needs: Python and uv (commands run via uvx)

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add mcp-state-sidecar -- uvx mcp-state-sidecar
```
uvx runs the command named after the package; if the README names another one, use uvx --from mcp-state-sidecar <command>

### Codex

**Platform CLI**
```bash
codex mcp add mcp-state-sidecar -- uvx mcp-state-sidecar
```
uvx runs the command named after the package; if the README names another one, use uvx --from mcp-state-sidecar <command>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "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>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "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>

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add mcp-state-sidecar uvx mcp-state-sidecar
```
uvx runs the command named after the package; if the README names another one, use uvx --from mcp-state-sidecar <command>

## When to use it
- 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
- Create a workflow tagged `ingest` and show me the `run_id`
- Claim that `run_id` for `worker-3` and checkpoint step 2
- Save context for session `session-42`, then restore it

## Similar
- [REA](https://affpapa.org/en/nevibecode/mcp/rea.md) — MCP server · ★ 386989
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33918
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81115
- [browser-use](https://affpapa.org/en/nevibecode/mcp/browser-use.md) — MCP server · ★ 119160
- [Codebase Memory](https://affpapa.org/en/nevibecode/mcp/codebase-memory.md) — MCP server · ★ 47392
- [mcp-server](https://affpapa.org/en/nevibecode/mcp/mcp-server.md) — MCP server · ★ 43872

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md