> Markdown export: /developers/mcp-tools.md
> HTML: /developers/mcp-tools
---
description: Complete MCP v1 tool reference — arguments, responses, auth, and security boundaries.
audience: integrator
---

# 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](/developers/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:

1. Call `retrieve_thoughts` with the question as `query`
2. 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:

```json
{
  "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](/developers/troubleshooting) — MCP section for 401 errors and empty results.

## Next steps

- [MCP overview](/developers/mcp-overview)
- [First memory walkthrough](/developers/first-memory-walkthrough)
- [HTTP API overview](/developers/http-api)