mcpstate

Durable, user-keyed state for stateless MCP servers.

State that follows the user, not the session.

mcpstate gives MCP agents state that survives the end of a conversation — and a switch to a different client, or a move to a different device. It ships as a Python library plus a ready-to-run MCP server. Start a research session in Claude Desktop on your laptop; continue it tomorrow from Claude Code, or from your phone.

See it work

The demonstration below is real. Each step is a separate operating-system process calling the actual MCP tools, sharing one on-disk backend — so the state surviving between steps is genuine durability, not a mock. Reproduce it with examples/research_assistant.py; full walkthrough in docs/use-case.md.

A new conversation the next day recovers exactly where you left off:

Two devices editing at once — the conflict becomes a merge the agent performs, and no write is lost:

Why this exists

The MCP specification revision of 2026-07-28 made the protocol stateless: Mcp-Session-Id, the initialize handshake, and SSE resumability were all removed (changelog, announcement). Sessions fought load balancers; the spec chose horizontal scale.

The spec's official answer for stateful servers is the handle pattern: mint an explicit handle (a basket_id, a research_id) from a tool, and have the model pass it back as an ordinary argument. How a server persists what a handle points to is explicitly out of scope — so every stateful MCP server now needs a durable, user-scoped, expiring handle store, and nothing standardizes one. mcpstate is that store.

What you can build with it

Any agent whose work is worth keeping between turns:

The three axes of continuity all fall out of one idea — state keyed by the user, not the connection:

flowchart LR
    subgraph a [Mon · laptop]
        A[Claude Desktop]
    end
    subgraph b [Tue · laptop]
        B[Claude Code]
    end
    subgraph c [Tue night · phone]
        C[Claude app]
    end
    A -- "research_k3v9x2mq" --> S[(mcpstate)]
    S -- resume --> B
    B -- save --> S
    S -- resume --> C

Quickstart — end users (the flagship server)

One config entry gives every agent you run durable memory:

pip install "mcpstate[fastmcp]"

{
  "mcpServers": {
    "state": { "command": "mcpstate", "args": ["serve"] }
  }
}

The server exposes six tools, written to be driven by a model:

For cross-device reach, point every device at a shared Redis:

{ "args": ["serve", "--backend", "redis://your-redis-host:6379/0"] }

Quickstart — server authors (the library)

pip install mcpstate

from mcpstate import HandleStore, Append, StaleWrite

store = HandleStore.from_url()  # default: sqlite:///~/.mcpstate/state.db

# Mint: create durable state, get back an opaque handle for the model to carry.
handle = store.mint("research", {"sources": [], "notes": ""}, user="alice", ttl_days=7)

# Read: state plus the freshness metadata you need to write it back.
snap = store.get(handle, user="alice")

# Versioned save: declare which version you read. If another session wrote in
# between, you get a StaleWrite carrying the current state — hand it to your
# model to merge and retry.
try:
    store.save(handle, {**snap.state, "notes": "arm64 wins"}, user="alice",
               expect_version=snap.version, writer="laptop/claude-code")
except StaleWrite as conflict:
    current = conflict.details["current"]  # full current snapshot, agent-legible

# Commutative patch: additive edits skip version checks entirely — two devices
# appending at the same moment both land.
store.patch(handle, [Append("sources", "https://arxiv.org/abs/...")],
            user="alice", writer="phone/claude")

# Renew the TTL from now — do this before it elapses; expired state is gone.
store.touch(handle, user="alice", ttl_days=7)

# Resume, any session later: what was this user working on?
for info in store.list("alice", kind="research"):
    print(info.handle, info.updated_at, info.last_writer)

Async server? AsyncHandleStore mirrors every method with the same semantics, running each call on a dedicated worker pool so backend I/O never blocks your event loop: store = AsyncHandleStore.from_url(); await store.get(handle, user=...).

The conflict model

mcpstate implements hand-off sync: state moves between sessions like a relay baton — one active writer at a time is the expected case, and the rare overlap is detected and surfaced, never silently clobbered.

The design bet: your client is an LLM. Traditional sync needs CRDTs because their clients can't reason about a conflict. An agent can. A losing write gets back a structured rejection containing the winner's state and an instruction to re-read and re-apply — and the model performs a semantic merge:

sequenceDiagram
    participant L as Laptop agent
    participant S as mcpstate
    participant P as Phone agent
    L->>S: get(handle) -> version 4
    P->>S: get(handle) -> version 4
    P->>S: save(state', expect_version=4)
    S-->>P: ok, now version 5
    L->>S: save(state'', expect_version=4)
    S-->>L: StaleWrite: modified by phone, now v5, here is the current state
    L->>L: merge intent with phone's state
    L->>S: save(merged, expect_version=5)
    S-->>L: ok, now version 6

Three mechanisms, cheapest first:

1. Versioned saves — every snapshot carries a version; save declares the version it read; a mismatch raises StaleWrite with the current snapshot.

2. Commutative patches — Append / SetKey / DelKey / Merge apply without version checks, so every writer's patch lands and a patch never sees a StaleWrite. Most agent-state mutations are additive, so most writes never see a conflict at all. (Precisely: Append is fully conflict-free; two sessions SetKey/Merge-ing the same key resolve last-write-wins for that key — the freshness metadata shows who won.)

3. Freshness metadata — every read returns version, updated_at, and last_writer, so a resuming session knows what changed while it was away.

See docs/concepts.md for the relay-baton model, why hand-off (not CRDTs) is the right v1, and the honest limits.

Backends

flowchart TD
    T[flagship server tools] --> HS[HandleStore]
    LIB[your server's own tools] --> HS
    HS --> B{backend URL}
    B -- "sqlite:///..." --> SQ[(SQLite · one machine, zero config)]
    B -- "redis://..." --> RD[(Redis · shared, cross-device)]

One durability note: Redis persistence is what your Redis is configured for — with default snapshotting, a crash can lose the last seconds of writes. For state you cannot afford to replay, enable AOF (appendfsync everysec or stricter) on the Redis you point at.

Four environment variables configure it: MCPSTATE_BACKEND (backend URL, or --backend), MCPSTATE_USER (identity for local/stdio; remote servers resolve the OAuth subject instead), MCPSTATE_WRITER (the last_writer label; defaults to hostname), and MCPSTATE_MAX_STATE_BYTES (per-handle state cap; default 1 MiB).

Results & credibility

Everything below is reproducible from a clean checkout with python3 -m pytest.

• 168 tests, green on Python 3.11 through 3.14 in CI — with ruff and a clean mypy --strict pass on every push.

• One backend contract suite runs against both SQLite and Redis, so the two backends are held to identical semantics — not tested separately and hoped to match. (Redis is exercised via fakeredis; a real-Redis CI job is on the roadmap.)

• Concurrency is tested, not assumed. Threaded race tests assert that exactly one writer wins a contended save while every commutative patch lands, on both backends. A contention test drives 8 threads × 20 patches at one handle and asserts all 160 land.

• Hardened against two rounds of adversarial review. Round one attacked user isolation, injection, resource exhaustion and API contracts. Round two (0.3.0) found and fixed four ways state could be silently lost or retained — see the changelog. Both rounds confirmed the core CAS engine and user-scoping sound: SQLite's conditional UPDATE and Redis's WATCH/MULTI are genuinely atomic, with no read-then-write window. Every finding was fixed with a regression test in tests/test_review_fixes.py.

• Zero required dependencies in the core library (redis and fastmcp are optional extras); ships py.typed.

Security and durability defaults worth knowing:

• State is capped at 1 MiB per handle (MCPSTATE_MAX_STATE_BYTES), and each user at 10,000 handles; both return structured errors rather than growing without bound.

• The SQLite database is created private to you (0600, in a 0700 directory).

• Credentials never appear in error messages, in userinfo or query-string form, and SQLite paths are never disclosed to clients.

• mcpstate serve --transport http fails closed — it refuses unauthenticated callers unless you pass --allow-anonymous, so a misconfigured server can't silently merge every user's state. Multi-user identity comes from FastMCP OAuth, issuer-scoped and percent-encoded.

• Expiry is judged by the backend's clock, so peers sharing one Redis can never disagree about whether a handle is still alive, and Redis enforces the TTL itself rather than leaving expired state resident until someone sweeps.

API reference

HandleStore

HandleStore(backend, *, max_state_bytes=1 MiB, max_handles_per_user=10_000, max_contention_seconds=5.0) — the guards are constructor arguments, so you can tune them per deployment.

Error codes

Every error carries .code and .to_payload() — a structured dict written for a model to read.

AsyncHandleStore exposes the same methods as coroutines (each call runs via a thread pool the store owns, so contended writes can never starve the rest of your application); construct it with AsyncHandleStore.from_url(...) or by wrapping an existing HandleStore.

Patch ops

path is a dotted path into the state ("profile.tags"); "" is the root. Every segment must already exist — patch ops do not create intermediate objects.

Roadmap

Deliberately out of scope so far, in rough order: append-only changelog and changes_since(handle, version) — so a resuming agent reads a delta instead of the whole state; richer commutative ops (set-add, list removal, counters, auto-vivifying paths); advisory activity leases; merge hooks / CRDTs behind the same handle API; push via the spec's subscriptions/listen; a real-Redis CI job; a Postgres backend and a non-Python sidecar.

Development

python3 -m pip install -e ".[dev]"
python3 -m pytest
python3 -m ruff check src tests
python3 -m mypy src/mcpstate

MIT licensed.