MCP tools reference

Spectron 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:///mcp` on SurrealDB Cloud.

Note

Older docs used names such as memory_store, memory_recall, and knowledge_search. Those prefixes are retired — use the short names above.

Note

REST-aligned responses use camelCase (queryMs, traceId, trace.traceId). Scope arguments are slash paths (for example org/acme/user/alice). Register paths with spectron scopes create before use.

Common fields

Tool responses correlate with graph-resident traces via **`traceId`** or **`trace.traceId`** (depending on the underlying endpoint). Use `GET .../traces/{traceId}` for the full record, or MCP **`inspect`** with `ref: "trace:"`.

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. Spectron auto-classifies content, reconciles against existing memory, and persists structured records.

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

Input

Field	Type	Required	Description
`text`	string	Yes	Content to remember
`session_id`	string	No	Existing session to append to
`scope`	string[] or nested arrays	No	DNF write selector within `memory:write`
`labels`	string[]	No	Descriptive `key=value` labels
`infer`	`"full"` \\| `"preview"` \\| `"none"`	No	Default `full`
`context_id`	string	No	Omit to use the bearer key's Context

Output

Structured diff: entities, attributes, relations, instructions, uncertainties, corrections, plus a stand-in trace_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

Field	Type	Required	Description
`query`	string	Yes	Natural-language question
`k`	integer	No	Hit count (default 10, max 50)
`mode`	string	No	`vector` \\| `bm25` \\| `graph` \\| `hybrid`
`lens`	string[] or nested arrays	No	DNF read lens
`labels`	string[]	No	Optional filters
`context_id`	string	No	Omit to use the bearer key's Context

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

Field	Type	Required	Description
`query`	string	Yes	What context to assemble
`lens`	string[] or nested arrays	No	DNF read lens
`labels`	string[]	No	Optional filters
`context_id`	string	No	Omit to use the bearer key's Context

`reflect`

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

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

Input

Field	Type	Required	Description
`query`	string	Yes	Synthesis question
`persist`	boolean	No	Default `false`
`context_id`	string	No	Omit to use the bearer key's Context

`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

Field	Type	Required	Description
`query`	string	Yes	What to stop believing
`purge`	boolean	No	Also erase supersession history
`context_id`	string	No	Omit to use the bearer key's Context

`upload`

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

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

Input

Field	Type	Required	Description
`bytes_base64`	string	Yes	Document bytes (RFC 4648)
`title`	string	No	Display title
`source`	string	No	Provenance string
`mime_type`	string	No	MIME type
`filename`	string	No	Original filename
`scopes`	nested arrays	No	DNF write selector (`scope` alias accepted)
`labels`	string[]	No	Labels on the document
`context_id`	string	No	Omit to use the bearer key's Context

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

Field	Type	Required	Description
`ref`	string	Yes	`entity:<Type>/<Name>`, `trace:<id>`, or `document:<id>`
`context_id`	string	No	Omit to use the bearer key's Context

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.