MCP Integration
Expose memory to agents over the Model Context Protocol:
GRAFOMEM_MCP_TENANT=acme grafomem serve --mcp stdio # local agent (e.g. Claude Desktop)
GRAFOMEM_MCP_TENANT=acme grafomem serve --mcp sse # remote agent over HTTP+SSE (port 8643)
One process, one tenant
An MCP process acts for exactly one tenant, given with --tenant <id> or GRAFOMEM_MCP_TENANT. Both shipped backends (SQLite and PostgreSQL) declare MULTI_TENANT, so the server refuses to start without it:
Error: --tenant (or GRAFOMEM_MCP_TENANT) is required: this backend declares MULTI_TENANT
and an MCP process serves exactly one tenant.
Every tool call is scoped to the bound tenant. A ref owned by another tenant is not found to this process — never read, deleted, or acknowledged. A caller-supplied tenant argument is accepted only if it names the bound tenant; otherwise the tool returns {"error": "tenant_mismatch"}.
To serve several tenants, run one process per tenant and route each identity to its own process at the gateway. With a shared process and no per-identity routing, every caller acts as the bound tenant — that is the gateway's responsibility, not the server's.
Tools
Seven tools are exposed:
| Tool | What it does |
|---|---|
write_memory | Store content (+ optional metadata); returns ref |
retrieve_memories | Semantic retrieval within a token budget |
list_memories | List the tenant's memories |
delete_memory | Hard-delete a ref; returns deleted, a sealed_probe (retrieval re-checked after delete), and certificate / certificate_status |
verify_erasure | Check a ref's erasure: certificate status, a storage read-back, optional re-probe |
run_conformance | Run one capability's conformance workload on a scratch store (see below) |
get_capabilities | Declared capabilities; with verify: true, run the conformance engine on each |
Erasure certificates over MCP
delete_memory issues a certificate only when the process has an erasure service: a PostgreSQL backend, a signing key (ERASURE_SIGNING_KEY / GRAFOMEM_SIGNING_KEY) and a ledger URL (GRAFOMEM_LEDGER_URL). Otherwise the delete still happens and the response says so:
{"deleted": true, "certificate": null,
"certificate_status": "not_issued: no erasure service in this MCP process"}
verify_erasure verifies in-process against the same service. With no service and no certificate, a deleted ref reports "status": "NOT_FOUND" with storage_check.row_present: false — nothing is claimed beyond what was read.
Conformance over MCP
run_conformance never writes to the serving store. SQLite servers get a temporary scratch store automatically; on PostgreSQL the tool returns an error pointing at grafomem conformance -b postgres --db <scratch> instead (a scratch schema needs DDL the runtime role does not have).
Verdicts come from the engine: PASS / VIOLATION with the per-direction results, NOT_DECLARED for a capability the backend does not declare (never PASS), UNTESTED for declared-but-no-result, ERROR: <reason> when the run failed. evidence.rollup_hash is a digest over the actual results; evidence.store names the scratch instance tested.
Transport notes
- In stdio mode nothing but JSON-RPC goes to stdout; the banner and status lines go to stderr.
- There is no native Streamable HTTP transport yet; gateways that bridge stdio (e.g. agentgateway) work.
Source: src/aml/server/mcp.py, src/aml/cli.py · Decision records: ADR-0016, ADR-0017, ADR-0018 in the grafomem repo.