Skip to main content
Glama
MCP State Sidecar Server

MCP State Sidecar Server

by askadvaith

MCP State Sidecar Server

PyPI version PyPI - Python Version License: MIT MCP Registry

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-sidecar

If you want to use the Redis backend:

pip install mcp-state-sidecar[redis]

Building from Source

To build and install the package from source:

  1. Clone the repository:

    git clone https://github.com/askadvaith/MCP-State-Sidecar.git
    cd MCP-State-Sidecar
  2. Install build dependencies:

    pip install --upgrade build
  3. Build the wheel and source distribution:

    python -m build
  4. Install the package locally:

    pip install dist/mcp_state_sidecar-*.whl

    Or 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-http

By 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-sidecar

Configuration

The server is configured entirely using environment variables:

Environment Variable

Default

Description

STATE_BACKEND

sqlite

Storage backend: sqlite or redis

DB_PATH

state_sidecar.db

Path to the SQLite database file

REDIS_URL

redis://localhost:6379

Redis connection URL

SIDECAR_HOST

0.0.0.0

IP host to bind the HTTP SSE server

SIDECAR_PORT

8000

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 (returns found=False if 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 unique run_id.

  • workflow_discover(tags?, status?): Find workflows filtered by tags or status.

  • workflow_claim(run_id, agent_id): Atomically claim a created workflow.

  • 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 tools
history_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

    A3.9/5.0

    Scored across 19 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers