MCP server

Published 2026-08-19 · Last reviewed 2026-09-11 · Applies to SPM-Polaris

MCP gives a compatible agent five explicit tools to save, find, read, and delete your SPM memory — without changing how the agent talks to its model.

https://api.spmos.ai/mcp
Authorization: Bearer spm_live_...

The production server name is SPM. Tool names are exactly remember, recall, read, delete, and status.

Tools

Scopes: remember requires memory:write; recall, read, and status require memory:read; delete requires memory:delete. Selecting a non-empty user_partition additionally requires memory:partition.

What a recall result looks like

• answer is the single strongest piece of saved evidence — not a rewritten summary.
• evidence_refs keep the broader supporting set, each with a short-lived read token.
• Pass tokens to read verbatim (as a JSON array) to get the exact original text.
• When nothing qualifies, you get an explicit no-evidence result with a machine-readable reason — never an invented answer.
• evidence_decision is a machine-readable verdict on how strongly the returned evidence is backed (see below).

Choosing a recall depth

Omit depth to use your account default (auto until you change it in Settings → Memory). The three depths:

• fast — one bounded lookup, zero provider-token spend. Best for simple, well-named questions.
• auto — fast first; deeper multi-round gathering only when the fast answer is not confident enough. A question about something you never saved is declined without paying for deep gathering.
• deep — multi-round gathering from the start, for hard multi-part questions ("how do A and B each relate to C"). The response reports rounds used, provider tokens, latency, and why it stopped.

If no deep selector is configured, deep fails closed with DEEP_RECALL_UNAVAILABLE and auto simply stays on the fast path.

Choosing a recall lane

Memory enters through two kinds of channels: deliberate saves (remember, console, direct API writes) and passive captures from proxy traffic. The lane_policy parameter controls how they compete for recall seats:

• explicit_first (default) — deliberate saves hold recall seats first; passive captures fill in only when deliberate memory is not enough.
• blended — one shared pool, ranked purely by relevance.
• observed_only — answer only from passive captures; use it for "what did I say in chat" questions about proxy-captured content.

The Provider Proxy's own continuity lookups use blended. Lane ordering is active: explicit_first orders the final evidence set so deliberate saves lead and passive captures follow — across both candidate evidence and source spans, not just one of them.

Evidence decisions

Every recall response carries an evidence_decision object that says how strongly the returned evidence backs the answer:

• status — supported (the evidence passed the gate and backs the answer), insufficient (candidates were found but none proved the claim), contradicted (the verifier refuted the claim), or unknown (nothing to judge, for example no candidates).
• evidence_ids / source_ids — what the decision is based on.
• support_failure_kinds — when status is insufficient, why the candidates failed support (for example cjk_floor for a CJK coverage floor, ascii for an exact ASCII term, identifier for an unattested identifier).
• authority and reason — provenance of the judgment.

Treat only supported answers as settled. insufficient means nothing was proven yet — rephrase, raise top_k, or switch to deep and look again.

How agents are asked to use memory

SPM's MCP instructions ask capable agents to use memory quietly:

1. If an earlier decision, constraint, or progress update is missing from active context, call recall before asking you to repeat it.
2. Call read when the exact original text is needed.
3. Continue the task with the result, without narrating that memory was searched.
4. Not repeat an empty recall within the same logical turn.

Current files, Git state, and runtime observations remain authoritative when they may have changed since a memory was written. SPM cannot force every third-party MCP runtime to follow these instructions.

Client configuration

Codex:

[mcp_servers.spm]
url = "https://api.spmos.ai/mcp"
headers = { Authorization = "Bearer spm_live_..." }

Claude Code and generic MCP JSON:

{
  "mcpServers": {
    "spm": {
      "url": "https://api.spmos.ai/mcp",
      "headers": {
        "Authorization": "Bearer spm_live_..."
      }
    }
  }
}

Restart the client after adding a server so it reloads the tool catalog. A 401 invalid_token means the server was reached but the SPM key is missing, malformed, expired, revoked, or belongs to another environment.

Recommended round trip

1. remember with a stable idempotency key.
2. Poll status until the memory is ready.
3. recall with a natural-language question.
4. read when exact original text or multiple premises are needed.
5. delete test data when the workflow is complete.

After deleting a memory, reusing the same source_id returns 409 SOURCE_ID_PURGED until you clear memory and start fresh. Use a new source ID for genuinely new content.

The MCP service is memory-only. It does not proxy model requests and does not need a provider key.

Health

/health, /livez, and /readyz are unauthenticated probes. The MCP endpoint itself requires authentication.

One key, many end users

For a multi-user application, keep one application key and pass a stable opaque partition identifier, normally your internal user UUID, on every remember, recall, and read call for that user:

{
  "question": "Which writing style do I prefer?",
  "user_partition": "user-123"
}

Selecting a non-empty partition additionally requires the memory:partition scope. Partitions are isolated within the tenant, and a read token minted for one partition cannot be used in another. Omitting the field selects the tenant's default space.