MCP tools reference

SurrealDB Agent Memory exposes seven tools over the Model Context Protocol at /mcp: remember, recall, context, reflect, forget, upload, and inspect. All tools use the same Authorization: Bearer authentication as the REST API. Point the MCP URL at https://<your-context-host>/mcp on SurrealDB Cloud.

Common fields

Tool responses correlate with graph-resident traces via trace_id. Use GET .../traces/{traceId} for the full record, or MCP inspect with ref: "trace:<id>".

Every tool accepts an optional context_id. When omitted, the server uses the Context bound to the bearer API key. An explicit context_id that does not match that binding returns 401.

remember

Store a conversational exchange or free-text fact. SurrealDB Agent Memory auto-classifies content, reconciles against existing memory, and persists structured records.

REST equivalent: POST /api/v1/{context_id}/facts

Input

Output

mode, session_id, turn_id, chunk_id, preview, and an extraction object with the structured diff (entities, attributes, relations, actions, instructions, uncertainties, corrections), plus a stand-in trace_id that holds the turn id.

Example

Tool: remember
Input: {
  "text": "I just got promoted to VP of Engineering and I'm moving to Singapore next month.",
  "scope": ["org/acme/user/alice"]
}

recall

Unified search over experiential facts and document passages. Returns ranked hits (not a synthesised answer).

REST equivalent: POST /api/v1/{context_id}/query

Input

Output

tier, hits (each with id, text, source, score, and occurredAt or resource when present), query_ms, trace_id, and context_hits when the router gathered extra rows for synthesis.

Example

Tool: recall
Input: {
  "query": "What role does Alice have?",
  "k": 10,
  "lens": ["org/acme"]
}

context

Assemble a markdown context block for prompt injection (profile + relevant facts).

REST equivalent: POST /api/v1/{context_id}/context

Input

Output

context (the markdown block), tier, query_ms, and trace_id.

reflect

Synthesise insights across memory. Optionally persist with persist: true.

REST equivalent: POST /api/v1/{context_id}/reflect

Input

forget

Soft-delete attributes that match a natural-language query. Use purge: true for permanent erasure including history.

REST equivalent: POST /api/v1/{context_id}/forget

Input

upload

Upload a document (base64). Processing is asynchronous - poll with inspect or REST.

REST equivalent: POST /api/v1/{context_id}/documents

Input

Example

Tool: upload
Input: {
  "bytes_base64": "aGVsbG8=",
  "title": "Team handbook",
  "scopes": [["org/acme/team/eng"]],
  "labels": ["team=eng"]
}

inspect

Look up an entity, trace, or document by typed reference.

REST equivalents: GET .../entities/..., GET .../traces/{id}, GET .../documents/{id}

Input

Example

Tool: inspect
Input: {
  "ref": "document:01hx9…"
}

Errors

Operation failures return isError: true tool results with structuredContent.error.status mirroring REST (404, 403, 429, 401, 500). JSON-RPC error is reserved for protocol faults (bad params, unknown tool). Auth and missing-Context failures are masked as 401. See MCP tools - error handling.