MCP
Connect an agent to Recall over MCP and use its eleven tools.
Recall runs an MCP server at /mcp. It uses the same API keys and the same code paths as the REST API, so a key sees one workspace either way.
Connect
claude mcp add --transport http recall https://recall.zakiego.com/mcp --header "Authorization: Bearer rcl_..."Claude on the web (custom connector)
claude.ai signs in with OAuth instead of a key. In Claude, open Settings, then Connectors, then Add custom connector, and paste https://recall.zakiego.com/mcp as the URL. Leave the OAuth client ID and secret empty. Claude opens Recall, you log in, pick a workspace and press Allow. The connector then reaches that one workspace until you remove it.
Other clients
Any MCP client that speaks Streamable HTTP works the same way: point it at https://recall.zakiego.com/mcp and send the key in the Authorization header. Claude Desktop needs a local bridge. Connect an agent has the config for each client, and the dashboard's Connect page fills in a key for you.
Transport
- Streamable HTTP at
/mcp.GET,POSTandDELETEare accepted. - Stateless: every request gets a fresh server, there's no session id, and responses are plain JSON rather than an event stream.
- Auth:
Authorization: Bearer rcl_...(orX-API-Key), or an OAuth access token (rco_...). Without either the server answers401with aWWW-Authenticateheader that points OAuth clients at the protected resource metadata, and a JSON-RPC error:
WWW-Authenticate: Bearer realm="recall", resource_metadata="https://recall.zakiego.com/.well-known/oauth-protected-resource/mcp"{ "jsonrpc": "2.0", "error": { "code": -32001, "message": "missing or invalid API key or access token" }, "id": null }- OAuth: the authorization server is at
https://recall.zakiego.com/api/auth(metadata at/.well-known/oauth-authorization-server). It supports dynamic client registration, the authorization code flow with PKCE (S256) and refresh tokens. Access tokens last an hour and refresh tokens 30 days. Each token is tied to the workspace picked on the consent screen, and stops working if you leave that workspace.
The server sends short instructions to the client on connect. They say what Recall is and point the agent at get_playbook for the rules, with the playbook's version (it changes whenever the rules do):
Recall is a long-term memory of the user, their work and the people they know. Look things up here before answering about them.
Every agent on this workspace reads what add_memory saves, and newer facts supersede older ones on their own.
Call get_playbook before your first tool call. It returns the operating rules (playbook version <version>):
when to search and when to ask, what is worth saving and what never is, containers, how supersession decides,
event_date versus due_date and the time zone, people records, the limits, and the errors.
None of that is inferable from the tool schemas, so do not guess it.
Once per conversation is enough. If you are carrying rules from an earlier conversation and the version
above does not match the one they came with, they are stale: call get_playbook again and use the new text.The playbook
The rules an agent can't read from the tool schemas live in apps/server/internal/mcp/playbook.md, and get_playbook serves them: when to search before answering, what is worth saving and what never is, containers, how supersession decides between update, invalidate and conflict, event_date versus due_date and the time zone, people records, the limits and the error messages. The playbook ships inside the binary, so it always matches the deployed tools.
Its version is an FNV-1a hash of the text, as 8 hex characters. The same version is in the instructions, so an agent that kept the rules from an earlier conversation can tell they're stale without a tool call. Once per conversation is enough.
Tools
Every tool except get_playbook takes an optional container (1 to 128 characters). Without it, the server's default container is used. Results come back as one text block holding JSON, except get_playbook, which returns markdown.
get_playbook
Returns the operating rules as plain text: Playbook version: <hash>, a blank line, then the markdown. It takes no arguments, is read-only, and is listed first. Every key and OAuth token gets the same text.
add_memory
Saves text or a URL. Facts are extracted in the background, and contradicting older facts are superseded.
| Argument | Type | Required | Limits |
|---|---|---|---|
content | string | one of content, url | up to 1,000,000 characters |
url | string | one of content, url | http or https. A web page or PDF to fetch |
title | string | no | up to 300 characters |
source_id | string | no | 1 to 200 characters. Same dedupe as the API |
wait | boolean | no | Wait up to 60 s for extraction and return the facts |
document_date | string | no | YYYY-MM-DD. The day the content was written, e.g. an email's sent date. Relative dates resolve against it. Defaults to today |
container | string | no | 1 to 128 characters |
When both content and url are sent, url is used. Chats and file uploads aren't available over MCP. Send a chat as content, or use the REST API.
Without wait:
{
"id": "doc_...",
"container": "alice",
"status": "queued",
"sourceId": null,
"duplicate": false,
"note": "Queued. Facts appear within a few seconds."
}With wait: true, once the document is done:
{
"id": "doc_...",
"container": "alice",
"status": "done",
"duplicate": false,
"added": [],
"updated": [
{ "id": "mem_...", "fact": "Prefers Puma running shoes", "kind": "dynamic", "replaces": "mem_..." }
],
"invalidated": 0
}replaces is the id of the version that was superseded. A fact that conflicts with another one carries a reviewNote. A failed document adds error. If extraction takes longer than 60 s, you get the id back with "note": "Still processing after 60 s. Facts will appear when it finishes.".
search_memories
Hybrid keyword and semantic search over current facts, in English or Indonesian. No LLM call.
| Argument | Type | Required | Default | Limits |
|---|---|---|---|---|
query | string | yes | 1 to 2,000 characters | |
limit | integer | no | 10 | 1 to 50 |
include_chunks | boolean | no | false | Also search the raw text of saved documents |
container | string | no | server default | 1 to 128 characters |
[
{ "type": "memory", "id": "mem_...", "text": "Meets Clara every Tuesday", "score": 0.0328, "kind": "dynamic", "people": ["Clara Simmons"] },
{ "type": "chunk", "id": "chk_...", "text": "I switched to Puma running shoes.", "score": 0.0164, "document": "Running notes" }
]ask_memory
Asks a question in English or Indonesian and returns a short answer written only from stored facts, with citations. One LLM call, a few seconds. See Ask.
| Argument | Type | Required | Limits |
|---|---|---|---|
question | string | yes | 1 to 2,000 characters |
include_chunks | boolean | no | Also use the raw text of saved documents |
container | string | no | 1 to 128 characters |
{
"answer": "They wear Puma running shoes [1].",
"covered": true,
"citations": [{ "ref": 1, "type": "memory", "id": "mem_...", "text": "Prefers Puma running shoes" }],
"model": "claude-haiku-5-5"
}Errors (timeout after 90 s, gateway failures) come back as a tool error whose text is the same message the REST API returns.
get_profile
A short summary of who the subject is (static) and what's going on now (dynamic), plus the facts behind it.
| Argument | Type | Required | Limits |
|---|---|---|---|
query | string | no | up to 2,000 characters. Adds searchResults |
container | string | no | 1 to 128 characters |
{
"container": "alice",
"static": "Lives in Banjarbaru.",
"dynamic": "Prefers Puma running shoes.",
"updatedAt": "2026-11-09T08:01:00.000Z",
"staticFacts": ["Lives in Banjarbaru"],
"dynamicFacts": ["Prefers Puma running shoes"],
"searchResults": ["Prefers Puma running shoes"]
}staticFacts and dynamicFacts hold up to 25 facts each. searchResults (up to 10) is only there when query is set.
list_memories
Lists facts, newest first.
| Argument | Type | Required | Default | Limits |
|---|---|---|---|---|
cursor | string | no | nextCursor from the previous page | |
limit | integer | no | 50 | 1 to 200 |
history | boolean | no | false | Include superseded and deleted versions |
needs_review | boolean | no | false | Only current facts flagged as conflicting with another fact |
container | string | no | server default | 1 to 128 characters |
{
"memories": [
{
"id": "mem_...",
"fact": "Salary is paid weekly",
"kind": "dynamic",
"current": true,
"reviewNote": "Conflicts with \"Salary is paid on the last Friday of the month\": ...",
"createdAt": "2026-11-09T08:00:00.000Z"
},
{
"id": "mem_...",
"fact": "Contract with Vorneo ends at the end of 2027",
"kind": "dynamic",
"current": true,
"event_date": "2026-01-02",
"due_date": "2027-12-31",
"createdAt": "2026-11-09T08:00:00.000Z"
}
],
"nextCursor": null,
"containers": ["alice", "default"]
}containers lists the workspace's containers and is only included on the first page (no cursor). reviewNote is only present on flagged facts. event_date and due_date are only present when the fact has them, in short form ("2027-12" for a month). search_memories and add_memory with wait show them the same way.
upcoming
Lists current facts with a due date in the next N days, soonest first. Use it for "what's due soon" or before planning.
| Argument | Type | Required | Default | Limits |
|---|---|---|---|---|
days | integer | no | 30 | 1 to 366 |
past_days | integer | no | 0 | 0 to 366. Also facts that came due in the last N days |
all_containers | boolean | no | false | Every container in the workspace |
timezone | string | no | UTC | IANA zone for "today", e.g. Asia/Makassar |
container | string | no | server default | 1 to 128 characters |
{
"today": "2026-11-10",
"container": "alice",
"memories": [
{ "id": "mem_...", "fact": "Car insurance with Astra renews", "container": "alice", "due_date": "2026-11-16", "days_left": 6 }
]
}An unknown timezone returns an error result. See dates and reminders.
list_people
The people named in the container's facts, most recently mentioned first.
| Argument | Type | Required | Default | Limits |
|---|---|---|---|---|
query | string | no | up to 200 characters. Matches name, aliases, role, organization, emails and handles | |
sort | recent or name | no | recent | |
limit | integer | no | 50 | 1 to 200 |
offset | integer | no | 0 | nextOffset from the previous page |
container | string | no | server default | 1 to 128 characters |
{
"people": [
{
"id": "per_...",
"name": "Clara Simmons",
"aliases": ["Clara"],
"role": "Product designer",
"organization": "Vorneo",
"emails": ["clara.simmons@vorneo.id"],
"facts": 3,
"lastMentionedAt": "2026-11-10T01:20:00.000Z"
}
],
"total": 1,
"nextOffset": null
}Empty fields are left out.
get_person
One person and the current facts that mention them, newest first, with their sources. Pass id from list_people, or name, which matches names and aliases as whole words, ignoring case.
| Argument | Type | Required | Default | Limits |
|---|---|---|---|---|
id | string | one of id, name | up to 64 characters | |
name | string | one of id, name | up to 200 characters | |
history | boolean | no | false | Also include older versions of those facts |
container | string | no | server default | 1 to 128 characters |
{
"id": "per_...",
"name": "Clara Simmons",
"role": "Product designer",
"organization": "Vorneo",
"summary": "Leads the Vorneo listing page redesign.",
"facts": [
{ "id": "mem_...", "fact": "Meets Clara every Tuesday to review Figma mockups", "kind": "dynamic", "current": true, "createdAt": "2026-11-10T01:20:00.000Z", "source": "Weekly notes" }
]
}No match, or an id from another workspace, returns an error result.
list_documents
Lists saved documents (texts, URLs, files, emails), newest first, with their processing status. Use status: "failed" to find documents whose extraction gave up, for example after the LLM gateway was down longer than the job retries last.
| Argument | Type | Required | Default | Limits |
|---|---|---|---|---|
status | queued, processing, done or failed | no | Only documents with this status | |
cursor | string | no | nextCursor from the previous page | |
limit | integer | no | 50 | 1 to 200 |
container | string | no | server default | 1 to 128 characters |
{
"documents": [
{
"id": "doc_...",
"title": "Weekly notes",
"sourceType": "text",
"status": "failed",
"error": "gateway 502",
"createdAt": "2026-11-17T00:20:00.000Z"
}
],
"nextCursor": null
}url is only present on documents saved from a URL, and error only on failed ones.
retry_document
Queues a failed document for extraction again, the same as the dashboard's Retry button. Pass id from list_documents.
| Argument | Type | Required | Limits |
|---|---|---|---|
id | string | yes | up to 64 characters |
{ "id": "doc_...", "status": "queued", "note": "Queued again. Facts appear within a few seconds." }A document that isn't failed, or an id from another workspace, returns an error result. So does an imported email whose body has to be fetched again with the importer's Gmail access: an API key or OAuth token doesn't carry a user, so retry those from the dashboard.
Notes
- wait:
add_memorywithwait: trueholds the call until the document is done or failed, up to a fixed 60 s. Extraction runs in the single job loop, so the wait queues behind other work. On timeout the document keeps processing. - source_id: pass your own id for the source (for example
gmail:<message id>) so an agent that sees the same email twice doesn't add it twice. A repeat in the same container returns the existing document with"duplicate": trueand"note": "Already saved under this source_id.". Withwait, it waits on that document. - Edits, resolving review flags, deletes and people merges aren't MCP tools. Use the REST API or the dashboard.