MCP tools reference

In plain terms: The memory operations your AI assistant can call over HTTP MCP — capture, search, edit, and delete — with arguments and response shapes.

All tools require Authorization: Bearer <api-key>. Endpoint: https://<your-app-origin>/api/mcp.

HTTP MCP exposes four tools. The in-app chat agent has additional Notes tools (create_text_file, search_text_files, etc.) that are not available over HTTP MCP.

Responses are JSON. Embedding vectors are never included in tool results — see Embeddings boundary.

Who this is for

Integrators wiring MCP clients or validating tool contracts
Operators auditing what data leaves the deployment via MCP

capture_thought

Store a new raw thought. Tier 1 returns immediately after text persist; tier 2 enrichment (classify, embed, graph links) runs in the background.

Argument	Type	Required	Description
`raw`	string	Yes	Non-empty trimmed thought text
`captured_at`	string	No	ISO-8601 capture time for backdated memories
`as_user`	boolean	No	When `true`, store as the human user's memory (e.g. they asked you to remember this). When omitted on MCP API key auth, store as agent-authored
`author`	string	No	Optional API key prefix override for authorship attribution

Returns: Thought subset — id, normalized text, category, metadata. Natural-language stored-result summary.

Errors: 401 unauthorized; validation error if raw is empty.

retrieve_thoughts

Read stored thoughts. Defaults to user-authored open memories (excludes agent captures and completed/archived).

Search mode (with query, default order=relevance): hybrid semantic, lexical, and precomputed graph-neighbor search over open thoughts, plus lexical search over attached text notes.

Browse mode (omit query or set order=created_at): newest open thoughts first — replaces the old list_thoughts tool. Paginate with cursor_created_at + cursor_id.

Argument	Type	Required	Description
`query`	string	No	Search text. Omit to browse recent thoughts
`order`	string	No	`relevance` (default, requires query) or `created_at` (newest first)
`top_k`	number	No	Max results (default 10)
`threshold`	number	No	Filter by normalized score in `[0, 1]`
`mode`	string	No	`fast` or `full`
`detail`	string	No	`snippet` or `full`
`author`	string	No	`user` (default), `agent`, or `all`
`include_agent`	boolean	No	Shorthand for `author=all`
`cursor_created_at`	string	No	Pagination cursor (ISO) when browsing
`cursor_id`	string	No	Pagination cursor (thought UUID) when browsing

Returns: Array of thought matches with normalizedText, category, score, and metadata. Query embeddings are computed in-process for SQL distance only — not returned.

edit_thought

Natural-language edit of an existing committed thought. Covers text changes and lifecycle updates (mark complete, archive, reopen).

Argument	Type	Required	Description
`thought_id`	string	Yes	Target thought UUID
`edit_request`	string	No	Edit request in plain language
`raw_text`	string	No	Direct text replacement (skips LLM processing)

Returns: { "ok": true, "thought": { ... } } or not-found indication.

Side effects: Re-embeds, updates graph node, re-syncs relations, logs activity.

delete_thought

Archive (soft-remove) a thought owned by the caller. Reversible — same family as edit "archive" / "not relevant".

Argument	Type	Required	Description
`thought_id`	string	Yes	Target thought UUID

Returns: Success confirmation or not-found.

Grounded answers (no dedicated MCP tool)

HTTP MCP does not expose answer_question. To answer a user question from memory:

Call retrieve_thoughts with the question as query
Compose the answer in your client using the returned thought texts and citations

The in-app Chat UI (/chat) does this internally via its agent tool loop.

Example JSON-RPC flow

MCP clients send JSON-RPC 2.0 messages. Conceptual tools/call payload:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "capture_thought",
    "arguments": {
      "raw": "Remember: team standups are Tuesdays at 10am."
    }
  }
}

Exact wire format follows the MCP Streamable HTTP specification; client libraries handle serialization.

Error codes

HTTP	Meaning
401	Missing or invalid API key
400	Validation failure (empty query, out-of-range `top_k`, etc.)
500	Pipeline failure (LLM gateway down after retries, DB error)

LLM calls retry exactly 3 times then return an explicit error — no silent fallback.

Troubleshooting

See Troubleshooting — MCP section for 401 errors and empty results.