Skip to main content

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:

ToolWhat it does
write_memoryStore content (+ optional metadata); returns ref
retrieve_memoriesSemantic retrieval within a token budget
list_memoriesList the tenant's memories
delete_memoryHard-delete a ref; returns deleted, a sealed_probe (retrieval re-checked after delete), and certificate / certificate_status
verify_erasureCheck a ref's erasure: certificate status, a storage read-back, optional re-probe
run_conformanceRun one capability's conformance workload on a scratch store (see below)
get_capabilitiesDeclared 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.