MCP Reference

RememberStack has two deliberately separate truth layers. Claims are immutable source testimony (“what was asserted, by whom, when”); facts—relations and observations—are the adjudicated worldview (“what the system holds or held true”): supersession-adjudicated, clocked on two time axes (when a fact held in the world, and when the system learned it), evidence-counted per distinct source—repetition is not corroboration—and contradiction-tracked. The fact_claim_evidence association is the auditable bridge between the layers, recording which claims support or contradict each fact. Query claims to inspect testimony; query facts to answer current or historical truth questions, then follow the bridge to see why the system believes or believed the fact.

(Internally these guarantees are decisions D41 and D54.)

Tool surface

The MCP surface exposes the deployment's four assured-operation registry rows as MCP tools. That namespace is closed: adding a query pattern means adding an examples.* saved query, not another tool. MCP, the API's /operations, and the CLI's remember operations list all render the same four registry-backed operations.

There is no generic recall or search MCP alias. Low-level direct primitives remain HTTP/SDK infrastructure; MCP agents use the assured operations or the open-query surface.

When the open-query facade is composed, seven static open-query infrastructure tools are listed alongside operation tools. Local and remote MCP share the same schemas and strict argument validation. Shipped examples.* saved queries are never top-level tools — they run only through run_saved_query.

Write tools (ingest, pipeline_readiness) are always present on the remote stdio server (remember mcp). The in-process OperationMcpServer advertises them only when both ingest and pipeline-readiness ports are composed; operation-only compositions omit them rather than advertising tools that cannot run.

tools/list

Stable order:

1. Static write tools (when composed): ingest, pipeline_readiness
2. Assured operations from the registry (GET /operations / in-process registry). Remote MCP treats HTTP 404 on GET /operations as “registry not mounted” and still returns the write tools. Auth and transport failures on GET /operations still fail tools/list. A missing or untrustworthy GET /query/space only omits open-query tools.
3. Open-query tools when the open facade is composed

The operation registry contains exactly: resolve_entity, claims_and_sources_context, facts_context, and combined_context. The eighteen demoted patterns are discoverable examples.* saved queries, not tools.

ingest

Exactly one body source:

Prefer source_kind + a stable source_ref for durable agent memory so later writes version the same document. Omit both only for intentionally anonymous one-shot ingest.

Optional: mime, title, source_kind + source_ref (must be paired), versioning_mode (snapshot | living), source_modified_at (timezone-aware UTC ISO-8601), source_version_ref. Lineage fields require the source_kind/source_ref pair (same contract as the SDK and HTTP API).

Success includes the engine IngestedVersion fields plus async guidance:

{
  "deployment_id": "…",
  "doc_id": "…",
  "version_id": "…",
  "content_hash": "…",
  "created": true,
  "pipeline": {
    "status": "accepted_not_ready",
    "next_tool": "pipeline_readiness",
    "poll_with": {
      "version_ids": ["…"],
      "require": { "pipeline": true, "p1": true, "live_graph": true, "p3": false }
    },
    "guidance": "Ingest accepted. Wait until pipeline_readiness.ready is true …"
  }
}

Ingest is asynchronous. Structure alone has been measured at many minutes; the tool does not block until ready. When created=false the content-hash no-op applied — call pipeline_readiness once rather than assuming work is in flight.

Body size limits are enforced by the deployment. Client preflight applies only when a served capability document supplies a max body size; otherwise the server rejects and the tool maps body_too_large / empty_body. Path reads additionally apply a local resource guard (REMEMBERSTACK_MCP_PATH_READ_MAX_BYTES, default 256 MiB) when no capability limit is served — process safety on the MCP host, not a cloud ceiling (O1).

pipeline_readiness

Success content is the engine PipelineReadinessReport JSON (no second envelope).

Agent poll algorithm:

1. ingest → read version_id, created.
2. If created=false, call pipeline_readiness once with pipeline, P1, and live graph required and P3 false; if ready, recall; else poll.
3. If created=true, wait ~30s, then poll with the same exhaustive request (set p3=true only when you specifically need the published corpus tree).
4. While ready=false and no stage is failed / dead_letter: wait 30–60s (back-off, floor ~15s), poll again.
5. On ready=true: call the appropriate assured operation (often combined_context).
6. On failed / dead_letter: STOP polling and report the stage to the user — do not keep polling.
7. After ~20–30 minutes without ready=true and without a terminal stage failure: stop and escalate to the operator (include version_id and last stages[]).

Operation tools

Operation tools render from the registry:

{
  "tools": [
    {
      "name": "facts_context",
      "description": "Current or historical adjudicated facts matching a question …",
      "inputSchema": {
        "type": "object",
        "properties": {
          "query": { "type": "string" },
          "k": { "type": "integer", "minimum": 1, "maximum": 30 }
        },
        "required": ["query"]
      }
    }
  ]
}

The inputSchema is the contract an MCP client validates arguments against before calling — the same schema the API advertises at /operations for operation tools, and the static schemas above for write and open-query tools. Operation, open-query, and write dispatch reject wrong types, bool-as-int, missing required fields, and unknown keys rather than coercing them.

tools/call

• ingest / pipeline_readiness return JSON text; failures use a structured error object (code, message, http_status, retryable, agent_action, optional reason_code).
• Operation tools run the named operation and return its declared contract serialized to JSON in one text content block. Three return Envelope; combined_context returns ContextBundle/v2.
• Open-query tools return QueryResult/v1 or discovery/metadata JSON in one text content block.

{
  "content": [{ "type": "text", "text": "{ \"grain\": \"fact\", \"facts\": [ … ] }" }],
  "isError": false
}

Structured write-tool error example:

{
  "content": [{
    "type": "text",
    "text": "{\"code\":\"body_too_large\",\"message\":\"…\",\"http_status\":413,\"retryable\":false,\"agent_action\":\"…\"}"
  }],
  "isError": true
}

A tool the registry has no active row for, a call missing a required argument, or an open-query call with invalid argument types is a protocol error result (isError: true) with the reason in the text block — never an exception across the wire. The client re-plans against a stated failure. Remote read-tool API failures encode their public status_code, detail, and optional code below an error key in that JSON text. This preserves a typed 503 or query-rejection code for hosts that need to stop or re-plan while still using the ordinary MCP error-result envelope.

What the tools return

Three operation tools return the self-accounting envelope: the answer, its grain (fact / evidence / compiled / composite), its validity and freshness, and any typed negative. Because the grain travels with the answer, a client can tell a current-fact answer from what a source asserted — a operation that answers "what holds now" can never be one that returns evidence (the registry's grain bar guarantees it). combined_context keeps the complete evidence and fact envelopes in separate claims_and_sources and facts fields; it has no single output grain and never flattens the two authorities.

Open-query tools return QueryResult/v1 with grade exploratory_tabular or content-free discovery payloads. Caps, drops, and PostgreSQL snapshot timing are part of the contract.

Transport

Run remember mcp to start the dependency-light stdio JSON-RPC server. It reaches the deployment at REMEMBERSTACK_API_URL, uses REMEMBERSTACK_API_AUTHORIZATION when set, renders tools/list as write tools + GET /operations (omitted when that route is 404) + the seven open-query tools when composed, and proxies tools/call to POST /ingest, POST /readiness, POST /operations/{name}, or the matching /query/… route. The server supports the MCP initialize, tools/list, and tools/call lifecycle; notifications produce no response.

The operation registry and execution remain deployment-side. The MCP process is therefore a client transport, not another server composition and not a second tool registry.

MCP write tools and the four-operation D87 catalog ship together in the current surface. There is no recipe compatibility namespace.