DarkMatter MCP Server

Universal MCP server that emits Context Passport records for AI agent decisions and actions. Drop into any MCP-compatible client (Claude Code, Cursor, Cline, Continue, ChatGPT Desktop, Zed, Goose, and others) to give your agent a commit / verify / replay / export toolset for verifiable, tamper-evident records.

Built by DarkMatter. Implements Context Passport v2.0, an open CC0 standard. Records emitted by this server use RFC 8785 (JCS) canonicalization and are byte-equivalent across the Python and TypeScript reference SDKs.

Install

In your MCP client's config (claude_desktop_config.json, Cursor's mcp.json, etc.):

{
  "mcpServers": {
    "darkmatter": {
      "command": "npx",
      "args": ["-y", "@darkmatterhub/mcp-server"]
    }
  }
}

Restart the client. Five tools become available to your agent:

• darkmatter_commit — record an agent decision or action
• darkmatter_verify — check that the chain has not been tampered with
• darkmatter_replay — walk the full chain in order
• darkmatter_export — produce a portable proof bundle
• darkmatter_list_sessions — see what sessions exist locally

Bundles explain themselves

darkmatter_export produces a bundle that a stranger can act on. Alongside the records it carries the format name, a link to the specification, whether the chain was intact at export time, and the exact command to verify it in Python or TypeScript, plus what a failure looks like.

That matters because the bundle is the artifact that leaves your machine. It goes to an auditor, a regulator or a counterparty who has never heard of this format, and the whole claim is that they can check it without trusting whoever sent it. A bundle that does not say how is asking to be trusted.

Local by default, published when you ask

With no configuration the server keeps every record on your own disk. The chain verifies offline through darkmatter_verify, so you can evaluate the whole idea without an account.

Set an API key to publish records and get a link somebody else can check:

| Variable | Effect | |---|---| | DARKMATTER_API_KEY | Publishes each record to DarkMatter and returns a verify_url. Get one at darkmatterhub.ai. | | DARKMATTER_SHARE | Set to true to make published records readable by anyone with the link. Off by default, because publishing is not something to do to your records without being asked. | | DARKMATTER_API_URL | Override the API host. Defaults to https://darkmatterhub.ai. | | DARKMATTER_MCP_STORE_DIR | Where local records are written. |

commit reports which of the two happened, in the storage field. If publishing fails the record is still committed locally and the error is returned alongside it, so a network problem cannot cost you the record.

Changed in 0.3.0. Earlier versions returned a https://darkmatterhub.ai/r/{id} link for every commit while making no network calls at all, so the link always 404ed. A verification URL is now returned only when there is a published record behind it.

What gets captured

Whatever the agent (or user) explicitly invokes via darkmatter_commit. Auto-capture of every tool call without explicit invocation is a separate component (see Auto-capture below).

Example agent flow:

User:    Approve the refund for order #1247 and record the decision.
Agent:   Calls refund_order(1247).
Agent:   Calls darkmatter_commit({
           input: "Approve refund for order #1247",
           output: "Approved. $84.00 refunded to original payment method.",
           role: "compliance",
           event_type: "commit"
         })
Result:  { ok: true, passport: {...}, storage: "local", verify_url: null,
           note: "Saved locally and verifiable offline..." }

The passport is signed (if a key is configured), hash-chained to the previous commit in the session, and stored locally at ~/.darkmatter/mcp/<session_id>/chain.jsonl.

Storage

Default: local-only. Passports never leave the machine.

~/.darkmatter/mcp/
├── default/
│   ├── chain.jsonl        # append-only stream of all commits
│   └── latest.json        # most recent passport (used as parent for the next)
└── <other-session-id>/
    └── ...

To forward each passport to a DarkMatter receiving server in addition to local storage, set:

export DARKMATTER_API_KEY="dm_sk_..."

The forwarding is best-effort and never blocks the agent's tool call. Local storage remains the source of truth.

Auto-capture

The MCP server captures only what the agent explicitly invokes. To auto-capture every tool call and turn boundary in a specific dev tool (without the agent having to remember to call darkmatter_commit), install one of the dev-tool-specific adapters:

• darkmatter-hub/claude-code — auto-capture for Claude Code (Anthropic)
• Cursor adapter — planned
• OpenAI Codex adapter — planned
• Aider adapter — community-built welcome

Each adapter hooks into its specific dev tool's event lifecycle and routes events through this MCP server's darkmatter_commit tool. One canonical endpoint, many capture surfaces.

Verification

Records are valid Context Passport v2.0 artifacts. Verify with any conformant implementation:

pip install context-passport context-passport-conformance
context-passport-conformance --level signed     # 9/9 vectors, no --vectors-dir needed

The conformance package ships its vectors inside the wheel, so this is a one-line check against the public reference suite.

Or use the offline reference verifier directly on the JSONL file:

import json
from context_passport import verify_chain

with open("~/.darkmatter/mcp/default/chain.jsonl") as f:
    chain = [json.loads(line) for line in f]

print(verify_chain(chain))  # True if intact, False if tampered

Why MCP

MCP (Model Context Protocol) is becoming the universal interop layer for AI tools. Writing this server once means it works in every MCP-compatible client without per-client integration code. See the Context Passport for MCP proposal for the broader architectural rationale.

License

Apache-2.0. See LICENSE.

The Context Passport schema this server implements is released separately under CC0 1.0 at github.com/contextpassport/spec.

Related repositories

• github.com/contextpassport/spec — the open standard
• github.com/contextpassport/python — Python reference SDK
• github.com/contextpassport/typescript — TypeScript reference SDK
• github.com/darkmatter-hub/claude-code — auto-capture for Claude Code
• github.com/darkmatter-hub/darkmatter — DarkMatter receiving server