MCP tools
title: MCP tools description: Tools the Fathom MCP server exposes to Claude Code, Claude Desktop, Cursor, and other MCP clients. Generated from the running api's tool catalogue. audience: developer quadrant: reference last_verified: 2026-04-25 owners: [api/_tool_schema.py, addons/mcp-node/index.js]
MCP tools
When you connect Fathom to an MCP host (Claude Code, Claude Desktop, Cursor) via fathom-connect, the host gains access to these tools. Each one calls into the lake.
remember
Search your memories with a natural language query. Returns a trail of moments — conversations, notes, research, photos, sensor data — as an associative chain (first came to mind, which reminded you of...). Be descriptive: 'Nova mozzarella stretch kitchen photo' works better than 'nova'. depth='deep' (default) traces connections; 'shallow' is a single quick search.
Parameters:
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
query |
string | yes | — | What you're trying to remember. |
depth |
string | — | "deep" |
deep = trace connections; shallow = single search. |
limit |
integer | — | 20 |
Max results per step. |
radii |
object | — | — | Optional dimension weights for ranking — {semantic, temporal, provenance}. Shallow path only. |
tags_include |
array | — | — | Optional — only surface moments with ALL these tags. |
write
Persist a thought, observation, or discovery. Everything you write becomes part of you — a future self will find it when they need it. One idea per write.
Parameters:
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
content |
string | yes | — | What to persist. |
tags |
array | — | — | Tags for filtering (e.g. ['meeting', 'decision']). |
source |
string | — | "api" |
Source label. |
image_b64 |
string | — | — | Optional base64-encoded image bytes. Creates an image-modality delta with content as the caption. |
image_path |
string | — | — | Optional absolute path to an image file readable by the api server. Alternative to image_b64. |
recall
Examine your memories by tags, source, or time. For structured retrieval when you know what you're looking for.
Parameters:
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
tags |
array | — | — | Memories must have ALL these tags. |
source |
string | — | — | Filter by source. |
time_start |
string | — | — | ISO timestamp — only after this. |
limit |
integer | — | 30 |
Max results. |
mind_stats
Check the state of your memory — total moments, coverage, top tags. Quick self-check.
propose_contact
Propose a new contact for admin review. Use when you encounter a person the lake doesn't know about yet — a mention in chat, an unknown handle, a correspondent you've gathered enough evidence on to formally register. Writes a contact-proposal delta; an admin accepts or rejects. You never create contacts yourself.
Parameters:
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
display_name |
string | yes | — | How people refer to this person (required). |
candidate_slug |
string | — | — | Suggested URL-safe identifier ('nova', 'bob'). Lowercase, no spaces. Admin can override on accept. |
rationale |
string | yes | — | 1-3 sentences — who they seem to be, the evidence, why they should be a contact. |
source_context |
object | — | — | Optional hints — {chat_session, channel, handle, delta_ids, …} — whatever helps the admin verify. |
engage
React to a delta in the lake — refute a synthesis that's wrong, affirm a memory that keeps proving useful, or reply to something you're responding to. Your engagement becomes its own delta and shapes how the target surfaces in future recalls: refutes lower its rank and travel inline as reasoning the next recall sees; affirms raise it. Use this as the repair channel for bad sediment.
Parameters:
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
target_id |
string | yes | — | id of the delta you're engaging with. |
kind |
string | yes | — | refutes: disagree, lowers surfacing. affirms: useful/right, raises surfacing. reply-to: neutral conversational pointer. |
reason |
string | — | — | Your reasoning in prose. For refutes this is what future recalls see under the delta. |
deep_recall
Compositional memory query — build a multi-step plan across the lake. Primitives: search, filter, intersect, union, diff, bridge, chain, aggregate. Use when a single remember doesn't close the thread: e.g. 'what connects X and Y' (bridge two searches), or 'how has X changed over time' (search + aggregate by week).
Parameters:
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
steps |
array | yes | — | Ordered plan steps. Each has 'id' plus exactly one action key (search, filter, intersect, union, diff, bridge, chain, aggregate) and optional params (radii, tags_include, limit, group_by). |
see_image
View an image from a delta by its media_hash. Call this when you remember a moment that includes an image (the media_hash appears on the delta) and you want to actually see the pixels. Returns the image bytes so you can reason about what's there rather than guessing from the caption.
Parameters:
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
media_hash |
string | yes | — | The media_hash from a delta (hex string). |
mind_tags
Tag catalogue — what categories exist in your memory, with counts. Useful for orientation when you're looking for a domain you haven't touched in a while, or when you need to pick a consistent tag for a new write.
rename_session
Rename the current chat session — the name you pass becomes the title shown in the dashboard sidebar. Use this when the session is still showing its raw slug / UUID and needs a readable title, or when the user asks to rename the conversation. For the claude-code surface, session_id is your current session's id (injected at SessionStart). For consumer-api chat, the server fills it in from context. Never refuse a rename request — this is the tool for it.
Parameters:
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
session_id |
string | — | — | Session identifier to rename. Required over HTTP. In consumer-api chat, filled in from context so the model doesn't have to pass it. |
name |
string | yes | — | The new title, 1-6 words, lowercase, no slug-style hyphens. For explicit user requests, pass their requested string as-is. |
Calling tools
From an MCP host, tools are invoked by name with an arguments object. The MCP server proxies the call to the api at POST /v1/tools/<name> (under the bearer token configured in the host).
Direct from the api: curl -X POST 'http://localhost:8201/v1/tools/<name>' -H 'Authorization: Bearer <token>' -H 'Content-Type: application/json' -d '{ ...args... }'.