shared-context-mcp

shared-context-mcp

English | 简体中文

A shared whiteboard for multi-agent work — one append-only context ledger that a main agent and all its sub-agents read and write, so nobody works from a stale snapshot.

shared-context-mcp is a Model Context Protocol server that gives a fleet of agents one shared, immutable event ledger keyed by context_id. The main agent keeps collecting evidence and dispatching sub-agents; sub-agents pull new findings on demand, write back what they discover, and everyone sees the same growing timeline — including late-arriving evidence and conflicting conclusions. It is domain-agnostic: the engine knows nothing about your use case, so the same server powers incident response (RCA), code investigation, research orchestration, or anything else.

One context, shared by many agents. The main agent drives, sub-agents contribute, and the ledger keeps every finding — no re-briefing, no lost evidence, no overwrites.

Built in Go, single binary, official MCP SDK, Streamable HTTP, pure-Go SQLite. Drop it into Cursor, Claude, Comate, or any MCP client — or embed it into your own host with three function calls.

Why shared-context-mcp

The usual way to coordinate multiple agents is to inject a snapshot into each sub-agent's prompt at dispatch time. The moment you do that, the snapshot is stale: new evidence the main agent gathers afterwards, and findings from sibling agents, never reach the sub-agent. shared-context-mcp fixes the coordination layer and nails five things:

• 1. One shared, append-only ledger — no stale snapshots, no overwrites. Every event (observation, finding, evidence, conclusion) is immutable and ordered by a global monotonic seq. Corrections are new events, not edits. Conflicting conclusions live side by side for a human or the main agent to adjudicate — the engine never silently merges or drops anything.
• 2. Incremental since cursor + snapshot injection — cheap to stay current. Dispatch with a snapshot (optionally filtered by kind) and a since cursor; sub-agents call ctx_pull(since) to get only what's new. An urgent_pending count lets an agent notice high-priority facts (stop-loss took effect, blast radius grew) and pull early — without any push infrastructure.
• 3. Domain-agnostic engine — vocabulary lives in your skill, not the server. kind is a free string the engine never validates; payloads are opaque JSON. The event vocabulary, roles, and "when to checkpoint" contract live in a companion skill/config you swap per scenario. The same binary serves RCA today and code review tomorrow with zero schema changes.
• 4. Large results as evidence blobs — the context window never blows up. Big logs, terminal dumps, and reports go into ctx_register_evidence (stored as a BLOB in the same DB, content-hashed) and events carry only a stable evidence_id. Agents read back exactly the byte range they need via ctx_get_evidence. No spill-TTL surprises, no giant payloads in the model context.
• 5. Cross-platform agent isolation with one HMAC token. Standard MCP has no unified agent-identity header, so authorization is a pure capability model: each context issues a short-lived HMAC context_token (bound to the context + a token_ver that a ctx_close bumps to revoke). Any standard MCP client — heterogeneous, any transport — joins a context simply by holding its token, and stays isolated from contexts whose tokens it does not have. Each agent's role travels as a producer_id / consumer_id parameter, not a header.

Plus the machinery that makes the above reliable:

• Idempotent writes. A dedup_key makes retries safe; a mismatched payload under the same key is a hard conflict, never a silent duplicate.
• Single-file, zero-ops storage. Pure-Go SQLite (modernc.org/sqlite, no cgo) in WAL mode — one file, cross-compiles anywhere. A Store interface leaves a clean seam to swap in PostgreSQL for scale, with the tool contract unchanged.
• Audit & retention built in. Every call logged as JSON with metadata only — never payload bodies or tokens (only a payload_sha256). Contexts (and their events + evidence) are purged after a configurable retention window.
• Standalone or embedded — zero host coupling. Run it as its own binary, or import the mcpserver package and register the tools onto your host's MCP server. It depends on nothing but the MCP SDK and its storage driver.

Quick start

Requires Go 1.25+.

export SHARED_CONTEXT_HMAC_SECRET="$(head -c 32 /dev/urandom | base64)"

# listen address is external-injectable: flag > env > config > default(127.0.0.1:8910)
go run ./cmd/shared-context-mcp --listen 0.0.0.0:8910
# or:  SHARED_CONTEXT_LISTEN=0.0.0.0:8910 go run ./cmd/shared-context-mcp
# or:  go run ./cmd/shared-context-mcp --config config.example.toml

The MCP endpoint is at /mcp over Streamable HTTP. Point your client at http://<host>:8910/mcp.

Tools

• ctx_open — create a context; the server mints an unguessable context_id and returns an owner context_token.
• ctx_issue_token — owner-only: mint a participant context_token bound to a producer_id (its role); hand each collaborating agent its own.
• ctx_append — append an immutable event (opaque JSON payload; dedup_key for idempotency). Producer is taken from the token.
• ctx_pull — incremental read by since cursor; returns next_since and urgent_pending.
• ctx_snapshot — full/filtered view for prompt injection; returns max_seq.
• ctx_register_evidence / ctx_get_evidence — store/read large results by evidence_id.
• ctx_close — owner-only: close a context (data retained for replay; all tokens revoked).

Embed in a host

mcpserver.Init("config.toml")
mcpserver.SetToolDescriptions(map[string]string{ /* per-platform overrides */ })
mcpserver.RegisterTools(hostServer, auditWriter) // register onto the host's MCP server

Configuration

Config file is optional; every value has a default. See config.example.toml. Precedence for the listen address: --listen flag → SHARED_CONTEXT_LISTEN env → config file → default 127.0.0.1:8910. The HMAC key is read from the env var named by token.hmac_secret_env (never stored in config); token.prev_secret_env enables zero-downtime key rotation.

Security

No built-in network auth beyond context tokens — bind to loopback or front with an authenticating proxy. Authorization is a pure capability model: ctx_open creates a context, mints an unguessable server-generated context_id, and returns a short-lived HMAC context_token. Whoever holds the id + token can operate on the context, so the main agent distributes both to the sub-agents it trusts. Because the id is random (an optional incident_id is stored as its own field, never baked into the id), a context cannot be squatted or joined by guessing keys; refreshing a token requires presenting the existing valid token. Tokens are revoked by a version bump on ctx_close; the producer_id / consumer_id parameters record each agent's role on events and in the audit log. Audit logs record metadata only, never payloads or tokens.

The name matches an existing open-source shared-context-mcp project; the collision is intentional.