# MCP tool reference > How memex speaks MCP, and what each of its tools does, takes and returns. Page: https://docs.memex.tools/mcp-tools memex speaks MCP over plain HTTPS at `https://memex.tools/mcp`: one JSON-RPC request per call, no streaming. A connection authenticates with the bearer token memex minted for it, either through the assistant's sign-in flow or a token you created on the **Other** tab of **Settings › Assistants**. An invalid or revoked token gets "Invalid or revoked token". Every note id on the wire is the note's number in your knowledge base, the same one in its address. Proposal and journal ids are numbered within your knowledge base the same way. Every tool has a title, which clients show in their list of memex's tools. Each call answers with structured JSON. A refused call (a missing argument, an anchor that no longer matches, an allowance reached, a role the token does not hold) comes back as a tool error with a sentence saying why. Lists page with `offset` and `limit` and report a `total`. Long note bodies page with `max_chars` and `body_next_offset`. > **Self-hosted memex** > > The address is the server's own, such as `http://localhost:8080/mcp`. Claude Desktop reaches the same tools through `app:mcp-stdio` inside the container. See [Connect assistants to self-hosted memex](https://docs.memex.tools/self-hosted-connect). The tools, in the order memex lists them: ## search Find notes by meaning and keyword, or browse. With a `query`, results are ranked as [How search works](https://docs.memex.tools/how-search-works) describes, and the same operators apply (`OR`, `NOT` or `-word`, parentheses, `"quoted phrases"`), matching words as written with no fall-back to meaning, which the reply says in `exact_match`. Without one, it lists notes filtered by `tags` (all must match) and `status` (`verified` or `pending`), ordered by `order` (relevance, or updated or created, ascending or descending). Up to twenty-five per page. Each result carries the id, title, description, status, source URL, tags and last update, and sometimes which section matched. Tag names that match nothing are reported back as `unknown_tags`. If meaning-search could not run, the reply says so in `semantic_search_unavailable`, and an empty result then means only that no note contains those words. Open to every role. ## get Read one note by id: the full body, tags, wiki-links and backlinks, status, description, who added and last edited it, and the true length of the body. If you flagged the note, `curation_flag` carries your comment, and the assistant is told to weigh it above its own reading. If the note is tagged `live-state`, `live_state_notice` carries the standing correction instruction; if it is tagged `user-profile`, `profile_notice` carries the reading instruction instead, or, for a profile still pending, the instruction not to follow it. For a long note the assistant can ask for a slice with `max_chars` and continue from `body_next_offset`; memex tells assistants not to give up on a note for being large. Open to every role. ## inbox What is waiting for you: counts of pending notes and held proposals, and the oldest of each kind up to `limit`, with proposed bodies only if `max_chars` is asked for. Read-only, for every role: an assistant can tell you what is waiting, and can avoid filing what a peer already filed, but nothing here approves anything. ## propose The one write tool, in two shapes. Without `note_id` it files a **new note**: `title` and `body_md` required, plus `summary`, `tags` and optionally a `source_url`. Assistants are told to write the description themselves, about two or three sentences, to call `list_tags` first and reuse your vocabulary, and to list what they consulted under a *Sources* heading at the end of the body. memex never describes or tags what an assistant writes: a note it saves without them waits in `needs_enrichment`. The note lands pending (agent) or verified (curator). With `note_id` it files an **edit**, sending only what should change: a new `title`, a full replacement `body_md`, or a `patch` (up to fifty ordered find-and-replace operations, each `find` copied exactly from the note and occurring exactly once; an empty `replace` deletes), plus `summary`, `tags` (the full new list) and a `change_title` of six or seven words with a `comment` reporting what the change does, one short sentence per change. A `summary` alone is a complete edit. For an agent the edit is held; for a curator a patch or a field change applies immediately, a whole `body_md` is held, and `hold: true` holds it on purpose. A held patch is checked again against the note as it stands when you approve it, so an anchor that has since changed is refused rather than misapplied. A `comment` with nothing else is a **report**: the note is unchanged, and the comment waits in your inbox as a staleness report. A second `propose` on a note the same connection already has in review revises that draft. The reply says which of these happened, and may add free `hints`: near-duplicates it noticed, notes the text names but does not link (with ready patches), and vocabulary tags the text uses, none of which was applied. If other notes cite this one, the reply says so and asks the assistant to check them. ## propose_delete Ask for a note to be retired, with a `reason` you can decide from. Held for every role. If other notes link to it, the reply asks where those links should point instead. ## propose_merge Ask for a duplicate to be folded into a keeper: `note_id` is absorbed, `into_note_id` survives and inherits its tags and backlinks, and `merged_body_md` optionally replaces the keeper's body. Held for every role. Both notes stay until you approve. ## needs_enrichment The backlog of notes with no description or no tags, oldest first, leaving out any note whose description is already waiting in your inbox. The intended loop is `get` a note and `propose` its description, one call per note. Open to every role; an assistant works it when you ask, never unasked. ## list_skills and get_skill The instruction sets memex serves to this connection: the shipped skills and your own served skill notes, each with a slug, title and description; then the full text of one by slug. The list is this connection's own, not everyone's, narrowed by the skill's enabled state, its tool and resource surface flag, and the connections it has been granted to. Assistants are told to check the list before a task that a skill might cover, and to follow what they load. Every tool result also carries `skills_version`, a short hash of that list; when it differs from the one this connection last saw, the result carries `skills_changed` too, the served list in one line, so a change made on the Skills page is learned on the connection's very next call. See [How assistants receive skills and instructions](https://docs.memex.tools/skills-over-mcp). ## list_tags Your vocabulary with a count per tag, the names you removed (with what they were merged into, so an assistant never proposes a retired word), and the three system tags marked with what each does. ## health Confirms the connection, gives this memex's address, names the connection and its role, and reports how much work is waiting (inbox counts and the enrichment backlog), so a scheduled run can stop when there is nothing to do. ## curation_candidates The curation queue: which notes need attention and why, ranked as [How curation works](https://docs.memex.tools/how-curation-works) describes, with counts per reason. `reason` narrows to one defect, `stale_days` to notes unread for that long, `cooldown_days` (seven by default) holds back recently curated notes, and `include_pending` adds pending notes as advisory. Notes another connection is currently working are withheld for up to half an hour. Open to every role. An empty result means there is nothing to do. ## blast_radius Notes whose linked neighbours changed recently, with what changed, so a pass can find notes left stale by an edit you, an agent or an import made; curators' own edits do not count. Open to every role. ## last_curated With no arguments, a preflight: when the last pass ran, what changed since, the size of the queue, and whether a pass is due. With `note_ids`, the last time each was curated. Open to every role; curators also see who and what. ## log Curator only. Append to the journal: a run summary (with the start time, the ids examined, and the counts the assistant claims, which memex checks against what it logged), an observation, or a tooling gap. A run summary that lists the notes it examined also releases the notes the queue was holding for that connection; otherwise they are released within half an hour. ## log_recent Curator only. Read the journal newest first: by default the curation record (what curators did, and your verdicts, flags and tag changes); for one note, everything done to it by anyone; or one kind of entry, or only the verdicts you marked as precedent. Assistants are told that your comments on their held items outrank their own judgment, and that a precedent applies to comparable cases from then on. ## resolve_curation_flag Curator only. Close your flag on a note by saying what was done about it. Disagreeing is a valid resolution. Refused while a delete or merge of that note is waiting for you, because your verdict on that proposal answers the flag. ## duplicate_candidates Curator only. Pairs of notes closest in meaning, with a distance, for a pass to open both and decide. `unsettled` counts notes still being compared; their pairs arrive on a later call. ## Connector filters Some assistants reach memex through a connector path that blocks text which looks like shell commands, answering with an HTML block page instead of JSON. Every write tool accepts `body_encoding: "base64"` as a retry: the assistant re-sends the same call with the free-text fields base64-encoded, including the `find` and `replace` of each patch operation, and memex decodes them so the note keeps its literal commands. ## Related - [How assistants receive skills and instructions](https://docs.memex.tools/skills-over-mcp): What memex tells an assistant when it connects, the ways skills are served, how a change reaches a connection, and the notices on live-state and profile notes. - [How connections work](https://docs.memex.tools/how-connections-work): The connection guides, signing in from an assistant, the first prompt, checking a new connection, permissions, tokens, and managing connections. - [How roles work](https://docs.memex.tools/roles): The agent and curator roles in full: what each may do without you, and how the curator role is granted. - [Connect an agent or a script](https://docs.memex.tools/connect-agent): Create a token in memex for a coding agent, an agent you run yourself, or a script.