MCP State Sidecar Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@MCP State Sidecar Server checkpoint workflow run-456 step 4 output 'all tasks passed'"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP State Sidecar Server
An MCP-native state sidecar that externalises workflow state for distributed agent deployments.
Quite a simple idea really; instead of storing state inside agents (which breaks when processes crash, scale horizontally, or span multiple frameworks), agents write to and read from this sidecar over the Model Context Protocol (MCP). The sidecar is itself an MCP server; agents call its tools exactly the same way they call any other tool!
The server itself is built with distributed environments in mind, and natively handles concurrency, crash resilience and atomic claims in addition to being a common interface for state management between agents.
Features
Durable Key-Value Store: CRUD operations with optional TTL (Time-To-Live).
Workflow Lifecycle Registry: Centralised coordination (create, claim, checkpoint, and resume) for distributed multi-agent workers without out-of-band communication.
TTL Leases & Locks: Concurrency control to prevent race conditions and split-brain scenarios.
Audit Logging & Session Snapshotting: Audit state transitions and persist session contexts.
Multiple Backends: SQLite (with WAL mode & serialisation) and high-concurrency Redis currently supported.
Related MCP server: nano-vm-mcp
Installation
Install the package via pip or your favorite Python package manager:
pip install mcp-state-sidecarIf you want to use the Redis backend:
pip install mcp-state-sidecar[redis]Building from Source
To build and install the package from source:
Clone the repository:
git clone https://github.com/askadvaith/MCP-State-Sidecar.git cd MCP-State-SidecarInstall build dependencies:
pip install --upgrade buildBuild the wheel and source distribution:
python -m buildInstall the package locally:
pip install dist/mcp_state_sidecar-*.whlOr install the package in editable mode for active development:
pip install -e .
Quick Start
Running the Server
In a multi-agent distributed environment, you would typically run the state sidecar as an HTTP SSE service so multiple remote agents and clients can connect to it concurrently.
HTTP SSE Mode (Primary for Distributed Environments)
Start the SSE server to listen on a network port:
mcp-state-sidecar-httpBy default, the server binds to 0.0.0.0 and listens on port 8000. The MCP endpoint is available at http://localhost:8000/mcp.
Stdio Mode (For Subprocess / Local Agent Execution)
Launch the server via standard input/output:
mcp-state-sidecarConfiguration
The server is configured entirely using environment variables:
Environment Variable | Default | Description |
|
| Storage backend: |
|
| Path to the SQLite database file |
|
| Redis connection URL |
|
| IP host to bind the HTTP SSE server |
|
| Port for the HTTP SSE server |
Tool Reference
Group 1 — Key-Value Store
state_set(key, value, ttl_seconds?, agent_id?): Upsert a JSON-serialisable value with optional TTL.state_get(key): Retrieve a value (returnsfound=Falseif missing or expired).state_delete(key): Delete a key.state_list(prefix?): List all live keys, optionally filtered by prefix.
Group 2 — Workflow Lifecycle
workflow_create(name, tags?): Register a workflow; returns a uniquerun_id.workflow_discover(tags?, status?): Find workflows filtered by tags or status.workflow_claim(run_id, agent_id): Atomically claim acreatedworkflow.workflow_checkpoint(run_id, step, output): Persist step output and advance the step counter.workflow_resume(run_id): Get full resume context including last step and all step outputs.workflow_status(run_id): Get lightweight status (status, last step, and timestamps).workflow_list(): List all registered workflows.
Group 3 — Lease & Concurrency Control
lease_acquire(resource_id, holder_id, ttl_seconds): Attempt to acquire an exclusive lock.lease_release(resource_id, holder_id): Voluntarily release a held lease.lease_renew(resource_id, holder_id, ttl_seconds): Extend lease duration without releasing.
Group 4 — Sessions & History
session_save(session_id, context): Save a snapshot of workflow context.session_restore(session_id): Retrieve saved context after crash or handoff.history_log(key?, n?): Retrieve the last N state-transition records with timestamps and writer IDs.
Group 5 — Observability
sidecar_health(): Liveness, backend type, uptime, and database metrics.sidecar_reset(): Irreversibly wipe all data.
License
This project is licensed under the MIT License. See LICENSE for details.
Available Tools
19 toolshistory_logB
Return the last N state-transition records in reverse chronological order.
Inputs: n, key. Returns: total, entries
lease_acquireA
Try to acquire an exclusive, TTL-based lease on a named resource.
Use this to prevent split-brain when multiple agents could simultaneously work on the same resource. Only one holder can hold the lease at a time.
If the current holder crashes, the lease expires automatically after ttl_seconds and another agent can acquire it.
Returns acquired=True on success with the expiry timestamp. Returns acquired=False with the current holder's ID on failure.
Inputs: holder_id (required), resource_id (required), ttl_seconds (required). Returns: holder, reason, acquired, expires_at, +1 more
lease_releaseA
Voluntarily release a lease this agent holds.
Only the current holder can release their own lease (holder_id must match). No-op if the lease has already expired or belongs to someone else.
Inputs: holder_id (required), resource_id (required). Returns: released, resource_id
lease_renewA
Extend an existing lease's TTL while still holding it.
Call this periodically from long-running agents to prevent their lease from expiring mid-execution. The holder_id must match the current holder.
Inputs: holder_id (required), resource_id (required), ttl_seconds (required). Returns: renewed, expires_at, resource_id
session_restoreC
Retrieve the workflow context saved for a session_id.
Inputs: session_id (required). Returns: found, context, session_id
session_saveC
Persist the full workflow context for a session_id.
Inputs: context (required), session_id (required). Returns: ok, session_id
sidecar_healthA
Check sidecar liveness and get backend diagnostics.
Inputs: no named parameters. Returns: status, backend, version, uptime_s, +2 more
sidecar_resetA
Wipe all sidecar state: kv_store, leases, workflows, step_outputs, history, and sessions.
Inputs: no named parameters. Returns: ok, cleared
state_deleteA
Delete a key from the state store.
Returns ok=True if the key existed and was removed, ok=False if the key was not found (idempotent — safe to call multiple times).
Inputs: key (required). Returns: ok
state_getA
Get the value stored under key.
Returns found=True and the value if the key exists and has not expired. Returns found=False and value=None if the key is missing or expired.
Inputs: key (required). Returns: key, found, value
state_listA
List all live (non-expired) keys, optionally filtered by prefix.
Example: state_list(prefix='fact_') returns all keys starting with 'fact_'. Returns an empty list if no keys match.
Inputs: prefix. Returns: keys
state_setA
Set a key-value pair in the shared state store.
The value can be any JSON-serialisable type (dict, list, str, int, …). If ttl_seconds is provided, the entry will expire automatically after that many seconds. Existing entries are overwritten silently. If agent_id is provided, it is recorded in the audit history so the caller can be identified in history_log results.
Use a structured key prefix to avoid collisions in multi-workflow deployments, e.g. 'shared:my_namespace:my_key' or simply 'fact_1'.
Inputs: key (required), value (required), agent_id, ttl_seconds. Returns: ok
workflow_checkpointA
Atomically persist a completed step's output and advance the step counter.
Call this immediately after each pipeline step completes, before starting the next one. A replacement agent can resume from the last checkpoint using workflow_resume().
The output can be any JSON-serialisable value (dict, list, str, …). If step N was already checkpointed, calling again with the same step overwrites the stored output (idempotent replay support).
Inputs: step (required), output (required), run_id (required). Returns: ok, step, run_id
workflow_claimA
Atomically claim a workflow for this agent.
Only succeeds if the workflow is in 'created' status. If two agents call this concurrently for the same run_id, exactly one will succeed.
After claiming, call workflow_checkpoint() as each step completes. If this agent crashes, use workflow_discover() + workflow_claim() from a replacement agent to resume — the sidecar preserves all checkpoint state.
Returns claimed=False with a reason if the workflow is already taken or does not exist.
Inputs: run_id (required), agent_id (required). Returns: reason, run_id, claimed, agent_id
workflow_createA
Register a new workflow and get back a unique run_id.
Call this from the orchestrator before spawning workers. The returned run_id is stored in the sidecar — workers do NOT need to receive it out-of-band; they use workflow_discover() to find it.
Tags are arbitrary key-value metadata used for discovery filtering: e.g. tags={'pipeline': 'data-etl', 'customer': 'acme', 'priority': 'high'}
Status starts as 'created'. Lifecycle: created → claimed → running → done/failed.
Inputs: name (required), tags. Returns: name, run_id, status
workflow_discoverA
Find workflows available for a worker to pick up.
Filters by tag key/value pairs (AND semantics) and/or status. Common usage: workflow_discover(status='created') to find unclaimed work.
Workers should follow this with workflow_claim() to atomically take ownership of one of the returned workflows.
Returns an empty list if no matching workflows are found.
Inputs: tags, status. Returns: runs
workflow_listA
List all registered workflows (all statuses).
For filtered listing, use workflow_discover(status=..., tags={...}) instead.
Inputs: no named parameters. Returns: runs
workflow_resumeA
Get everything a replacement agent needs to resume a crashed workflow.
Returns:
last_step: the highest step that was successfully checkpointed
step_outputs: dict mapping step number (as string) to its output
meta: full workflow metadata (name, tags, status, agent_id, …)
Inputs: run_id (required). Returns: meta, run_id, last_step, step_outputs
workflow_statusA
Get the current status of a workflow — lightweight alternative to workflow_resume.
Returns the status, last completed step, assigned agent, and timestamps. Does NOT return step outputs (use workflow_resume for that).
Inputs: run_id (required). Returns: run_id, status, agent_id, last_step, +2 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 19 tools
Each tool targets a distinct resource (history, leases, sessions, sidecar admin, state store, workflows) with clear boundaries. Even overlapping descriptions like workflow_list and workflow_discover are differentiated by purpose—list shows all, discover filters by tags/status—ensuring no ambiguity.
All tools consistently use snake_case with a noun_verb pattern (e.g., lease_acquire, state_get, workflow_create). Minor deviation like sidecar_health still follows the resource-first convention. No mixing of styles or irregular verbs.
19 tools cover multiple subsystems (leases, state, workflows, sessions, admin) without redundancy. Each tool has a clear role, and the count feels appropriate for the stated purpose of a sidecar server managing distributed state and workflow coordination.
The tool surface covers CRUD for state store, lease lifecycle, workflow creation and resumption, and admin operations. Minor gaps include no explicit tool to mark a workflow as failed/completed (only implied through checkpointing) and no update/delete for sessions. Overall, core workflows are well-supported.
Maintenance
Related MCP Connectors
Hosted MCP memory and agent control plane for durable conversations, jobs, and operations.
Idempotency keys, locks, timers, and inboxes for agents over MCP. No payments.
Private-by-default, local-first memory/context/task orchestrator for MCP apps and agents.
Workflow diagnostics, capability routing, and x402 settlement for MCP-compatible agents.
Related MCP Servers
- AlicenseAqualityDmaintenanceShared versioned state for multi-agent AI workflows. An MCP server.5144 PyPI2MIT
- AlicenseBqualityBmaintenanceGoverned agent execution gateway for LLM workflows, providing deterministic FSM-based execution, audit trails, and idempotency guarantees via MCP.6146 PyPIMIT
- FlicenseAqualityDmaintenanceAn agent-native workflow MCP server that enables AI agents to execute text-defined, versionable workflows with checkpointing and state management.10-
- AlicenseNot gradedqualityCmaintenanceDurable, user-keyed state management for stateless MCP servers. Enables agents to persist and resume state across conversations, clients, and devices.18 PyPIMIT