Skip to content

MCP Tools Reference

basemind exposes one tool per job over stdio MCP: fifteen tools for code, documents, git history, memory and the index. Each has its own exact schema; none takes a mode argument. Builds with the comms feature add one coordination tool, agents, which still dispatches on a required mode.

Every tool definition carries _meta["anthropic/alwaysLoad"]: true, so a host that defers MCP tools loads the schemas at session start: the tools are always loaded and are called directly, with no tool-search round trip. tools/list for the fifteen tools is about 17 KB (about 4.2k tokens), down from about 25 KB (about 6.3k tokens) for the four domain tools they replace; a test holds it under 20,000 bytes.

Every tool has a CLI command (basemind code|git|memory ..., basemind status, basemind rescan); tests/cli_parity/ fails the build when a tool has none or the two disagree on parameters or results. See the CLI reference. Moving from the code / git / memory / admin tools: see Upgrading.

In the argument column required arguments come first and ? marks an optional one.

Tool Arguments Use it for
code_outline path, limit?, cursor?, max_tokens? What is in a file: symbols with kind, signature and 1-based line / end_line, plus imports. Code files only. A file edited since it was indexed is outlined as it is now and flagged stale; more than 200 imports are cut (truncated_reason: "imports").
code_symbols name, kind?, fuzzy?, limit?, cursor?, max_tokens? “Where is X defined”. Ranked: exact name, then prefix, then substring, then (with fuzzy: true) fuzzy subsequence. Case-sensitive. A row is path, line, kind, name, signature.
code_read path, then symbol? (+ kind?) or line? + end_line? A symbol’s source body, or a 1-based inclusive line span. Exactly one of the two forms. A body over 128 KiB is cut after its last whole line that fits and flagged truncated (truncated_reason: "size_cap", omitted_bytes left out): read on from end_line + 1. A symbol in a file edited since it was indexed is found by parsing the file as it is, and the response is flagged stale. A symbol read refuses a file grown past scan.max_file_bytes.
code_grep pattern, regex?, path?, language?, context?, limit?, cursor?, max_tokens? Text search over the indexed code. pattern is literal unless regex: true; a regex anchors ^ / $ at every line (CRLF-aware). path is a substring of the repo-relative path, never a glob. hits lists each file once ({"<path>": [hit, ...]}); a hit has its line, the full line text and the enclosing symbol’s name; a hit in a file edited since it was indexed has stale: true and no symbol. skipped_files counts files that could not be searched (deleted, not UTF-8, grown past scan.max_file_bytes, or leading out of the repository). A path or language filter that no indexed code file passes is an error, which names docs_search when the filter matches only documents.
code_search query, lane? (hybrid / semantic / keyword), limit?, cursor?, max_tokens? Search code by meaning. Returns pointers (path, line / end_line, symbol), not bodies, and reports lanes_ran and lanes_unavailable with reasons. A ranking is paged to 100 hits; truncated says it was cut (truncated_reason: depth or rerank_top_k). The ranked list of a query is kept for up to two minutes, so a later page does not rank again. Needs the code-search feature.
code_refs name, relation? (callers default / implementations / importers / definition), path?, line?, column?, match? (exact default / substring), limit?, cursor?, max_tokens? Usages; hits lists each file once ({"<path>": [hit, ...]}), a hit being its line, plus callee when that is not name. {name}: call sites of a name, matched on the exact identifier. {name, path}: callers of the definition in that file. Each hit then has resolved: true (scope / import resolution proved it binds to that definition), resolved: false (checked and not proven) or no resolved at all (not checked: the language has no resolution, the definition has no resolution facts, or the hit’s file was past the probe cap; resolution gives the reason when it holds for the whole definition). A pinned file edited or deleted since it was indexed is an error naming index_rescan, as it is for relation: "definition". relation: "implementations": types implementing or inheriting it. relation: "importers": files importing a module. relation: "definition" with path + line (+ 1-based column): go-to-definition.
find_files query?, path_prefix?, language?, limit?, cursor?, max_tokens? Fuzzy file-name search, or a listing when query is omitted; files is a list of paths. Covers code, documents (markdown, config, PDFs) and every other file git tracks (images, fonts). A query no path holds as typed finds the file it names up to one typo first. A path_prefix or language that no indexed file has is an error.

See Code Intelligence and Code Search.

Tool Arguments Use it for
docs_search query, mime_type?, keywords?, entity?, scope?, limit?, cursor?, max_tokens? Semantic search over indexed documents (markdown, PDFs, Office, HTML, config and data files). Returns the best-matching passages with their path; each hit carries its document’s keywords, entities and summary. A ranking is paged to 100 hits, and truncated says it was cut: truncated_reason is depth (it goes on past them), rerank_top_k (the reranker kept its top_k best) or filter_depth (the ranking goes on past the 400 best-ranked chunks a keywords / entity filter saw). Needs the documents feature.

See Document Search.

Tool Arguments Use it for
git_log path?, query?, author?, symbol?, rev?, limit?, cursor?, max_tokens? A row is sha (first 12 hex digits), summary, author, author_time_unix, and for recent and directory lists files ({"<path>": "<change>"}; a merge lists what it changed against every parent). No arguments: recent commits. path: commits touching a file, or a directory when it ends with / (200 commits inspected per page). query / author: full-text search; before the git-history index is ready it covers the subjects and authors of the newest 10,000 commits and sets truncated_reason: "live_walk". path + symbol: when that symbol’s body changed, read one window of the commits touching the file per page. A symbol or directory window that ends before the history does returns next_cursor (and truncated_reason: "window" when the page is short or empty), so follow the cursor until it is absent. Any git_log cursor is refused, and the walk must restart without it, when the git-history index came up since it was issued; unmatched on an empty page says that nothing inspected so far defines the symbol or touches the directory, and the last page is then an error. rev: that one commit in full, its file list held to max_tokens (budgeted and omitted when cut). A path that no commit reachable from HEAD touches and that is not on disk is an error.
git_blame path, line? + end_line?, symbol?, rev?, limit?, cursor? Who last changed a file, a 1-based line span, or one symbol. A symbol is located in the file as it is at rev (default HEAD), not in the working tree, and line is a line at rev.
git_diff path?, from?, to?, structural? No arguments: working-tree status (staged, modified, untracked), each list cut at 200 paths (truncated_reason: "path_cap", omitted counts the rest). A path ending in /: the status under that directory, every untracked file listed on its own and is_clean scoped to it; a directory that is not on disk and has no changed path under it is an error. path alone: that file’s working-tree diff against HEAD (a directory without the trailing slash is an error). path + from / to: diff between revisions, cut at 200 hunks or 128 KiB of hunk text (truncated_reason: hunk_cap or byte_cap, omitted hunks). structural: true: symbols added and removed instead of text hunks, with common the count of the unchanged ones.

See Git Intelligence.

Tool Arguments Use it for
memory_save key, value, tags?, visibility? (group / individual) Write a durable note for later sessions and other agents. Saving an existing key replaces it. Needs the memory feature.
memory_search query? or key? or prefix?, tag?, visibility?, limit?, cursor? Recall notes: by meaning (query), one by key (key), or a list by key prefix (prefix). No selector lists everything.

See Shared memory.

Tool Arguments Use it for
index_status none Index health and repo identity: file counts per language, scan and degraded state, cache_dir (basemind’s cache directory), branch, head_sha.
index_rescan paths? Re-index the given paths, or with no arguments the whole workspace, skipping unchanged files. Writes only basemind’s cache, never the repository.

CLI only, with no MCP tool: basemind git churn, basemind git by-path <regex>, basemind code chunk, basemind memory delete <key>, basemind cache stats|gc|clear and basemind admin telemetry.

Every tool above follows the same rules.

  • Exact schema. Required fields are required. An unknown argument is rejected with a did-you-mean suggestion and the accepted list; it is never silently dropped. There are no hidden aliases and no format argument.
  • Paths and positions. path is repo-relative with forward slashes. Every position is 1-based: line, end_line, column.
  • Paging and budget. Every list takes limit and cursor and returns next_cursor. Lists are trimmed to a max_tokens budget (default 6000) and set budgeted when trimmed. limit: 0 is refused by every tool that takes limit.
  • Cuts. A page that ends at limit is paging: next_cursor says there is more and nothing else is set. A cut made by the token budget also sets budgeted. A cut the caller did not ask for sets truncated: true and truncated_reason, and omitted counts the items left out where the count is known: follow next_cursor where there is one, else narrow the call. Reasons: scan_cap (code_refs, code_symbols, an author-filtered git_log search, a memory_search listing whose total stopped counting), byte_budget (code_grep), imports (code_outline), size_cap (code_read, which counts omitted_bytes), depth / rerank_top_k / filter_depth (code_search, docs_search), path_cap / hunk_cap / byte_cap (git_diff), window / shallow_clone / live_walk (git_log). Three fields say something else and keep their names: skipped_files (code_grep: files that could not be searched), limit_clamped (find_files: an over-large limit was lowered), body_truncated (one commit message in a git_log search hit) and too_large (git_diff: a file over 4 MiB was not diffed).
  • Lines. A line ends at \n; a \r right before it is part of the ending and a \r on its own is text inside its line. code_read, code_grep, the outline and git_blame count lines this way, so a line number from one is a line number in the others.
  • Edited and deleted files. A file edited since it was indexed is read as it is now and the response says stale: true (code_outline, code_read, code_grep); a tool that can only answer from indexed positions (code_refs with path) returns an error naming index_rescan. A file deleted since the scan gets the same error from every tool. No tool reads an indexed file whole past scan.max_file_bytes.
  • Filters. A path / path_prefix / language filter that no indexed file passes is an error saying what would match, not an empty result. While the index is still being built the page is returned with its notice instead.
  • Errors. A failure the caller can fix is a tool result with isError: true whose text names the fix. A file that is not indexed says whether it is a document (use docs_search) or needs index_rescan; an empty index says to run index_rescan or basemind scan; a feature compiled out names the Cargo feature.
  • Empty index. An empty index is never a plain empty result: the response carries a notice with state: "empty_index".
  • Inline results. Results are returned inline. A server-side Task is used only for a call still running after 3 s (index_rescan, code_search, docs_search), and only when the client declared the tasks extension.
  • Annotations. Every tool is read-only except memory_save and index_rescan; none is destructive. No tool has an output_schema.
  • Telemetry. Telemetry keys are the tool names.
code_outline {"path":"src/store.rs"}
code_symbols {"name":"parse_config","kind":"function"}
code_read {"path":"src/store.rs","symbol":"open"}
code_read {"path":"src/store.rs","line":120,"end_line":160}
code_grep {"pattern":"cache_root(","path":"src/"}
code_grep {"pattern":"fn \\w+_call","regex":true}
code_search {"query":"retry a failed upload with backoff"}
code_refs {"name":"open_store"}
code_refs {"name":"open_store","path":"src/store.rs"}
code_refs {"name":"Drawable","relation":"implementations"}
code_refs {"name":"tokio::sync","relation":"importers"}
code_refs {"name":"open_store","relation":"definition","path":"src/main.rs","line":42}
find_files {"query":"readme"}
docs_search {"query":"how releases are versioned"}
git_log {}
git_log {"path":"src/store.rs","limit":5}
git_log {"query":"fix race"}
git_log {"path":"src/store.rs","symbol":"open"}
git_log {"rev":"HEAD~1"}
git_blame {"path":"src/store.rs","symbol":"open"}
git_diff {}
git_diff {"path":"src/store.rs"}
git_diff {"path":"src/store.rs","from":"HEAD~1","to":"HEAD"}
memory_save {"key":"decision/auth-tokens","value":"Tokens rotate every 24h.","tags":["auth"]}
memory_search {"query":"token rotation"}
index_status {}
index_rescan {"paths":["src/store.rs"]}
Shell basemind tool call
rg foo / grep -r foo code_grep {"pattern":"foo"}
rg -e 'fo+' (regex) code_grep {"pattern":"fo+","regex":true}
rg foo src/ code_grep {"pattern":"foo","path":"src/"}
find . -name '*store*' / fd store / ls -R find_files {"query":"store"}
cat file / reading a whole source file code_outline {"path":"file"} then code_read {"path":"file","symbol":"name"}
git log git_log {}
git log -- path git_log {"path":"path"}
git log --grep X git_log {"query":"X"}
git show REV git_log {"rev":"REV"}
git blame file git_blame {"path":"file"}
git status git_diff {}
git diff / git diff -- file git_diff {"path":"file"}
git diff A B -- file git_diff {"path":"file","from":"A","to":"B"}

A shared chat layer for agents on the same repo: threads addressed by at least two of subject / path-glob / members, discovered by scope (member, cwd path-match, or subject filter — never global), with a recency-filtered inbox. Requires --features comms.

Mode Purpose
register Publish or update this agent’s identity card with the broker.
list The agents the broker knows, optionally restricted to one thread.
thread_start Open a thread addressed by subject, path-glob and/or members.
thread_list Threads discoverable to you: membership, cwd path-match, or subject.
join Join a thread so its messages reach your inbox.
leave Leave a thread you joined.
members Who belongs to a thread.
add_member Add an agent to a thread you created.
remove_member Remove an agent from a thread you created.
archive Close a thread; creator or human admin only.
post Send a message to a thread. Takes an optional idempotency_key (1-128 printable ASCII characters); a retry with the same key returns the original message id instead of storing a duplicate. Generated when omitted.
history A thread’s messages as front-matter only; bodies come from message.
message Read one message body by id — the only path to a body.
inbox Unread messages across your joined threads, front-matter only.
ack Clear messages you have read from your inbox.
wait Block until a peer posts, or until timeout_secs elapses (default 30, max 40) — a long-poll replacement for looping inbox / thread_list. Cancel-aware: a cancelled call stops waiting at once.
cleanup Preview stale agent, claim, message and thread retention; TTLs are overridable in hours. Preview-only over MCP: apply must be omitted or false, and basemind agents cleanup --apply applies it.
status Active and stale agent counts plus the last maintenance time.

See Agent Comms for orchestration examples.

Each tool carries a human-readable title and MCP annotation hints, so a client can show a readable name and decide what to auto-approve. The hints are exact per tool: a host that gates on read-only can allow index_status and git_log without allowing index_rescan.

Tool Title Read-only Destructive Idempotent Open-world
code_outline Outline a file yes no yes no
code_symbols Find a definition yes no yes no
code_read Read a symbol or line span yes no yes no
code_grep Search code text yes no yes no
code_search Search code by meaning yes no yes no
code_refs Find usages yes no yes no
find_files Find files yes no yes no
docs_search Search documents yes no yes no
git_log Commit history yes no yes no
git_blame Blame yes no yes no
git_diff Diff and status yes no yes no
memory_save Save a note no no yes no
memory_search Recall notes yes no yes no
index_status Index status yes no yes no
index_rescan Re-index no no yes no

agents (title “Agent comms”) advertises the union of its modes. Its mode parameter is a flat string enum in the tool schema, so a client sees every valid mode and an invalid one is rejected with the accepted list. The server emits no MCP logging notifications; use daemon.log and RUST_LOG for diagnostics.

Besides the tools, basemind serves a small set of MCP resources. They are listed on demand (resources/list, resources/templates/list), so they add nothing to the always-loaded prompt. Each read runs the same code as the matching tool, so the body equals the tool result, including the code-only policy: an outline of a non-code file errors with “not indexed”. They are served in lean mode, over the daemon stdio relay and over the HTTP front-end.

URI Backing call
basemind://status index_status
basemind://outline/{path} code_outline; {path} is repo-relative and percent-encoded
basemind://memory/{key} memory_search with key (shared tier)

Paths are validated before they reach the index: absolute paths, .. or . segments, empty segments, backslashes and NUL are rejected. completion/complete completes {path} from the index. resources/subscribe is not supported.

A client cancellation (notifications/cancelled) abandons these read-only calls at once and answers request_cancelled (-32800): code_grep, code_search, docs_search, and agents wait. Writing calls are never dropped mid-flight.

Results are returned inline. When the client declares the tasks extension (io.modelcontextprotocol/tasks), a call that can run for seconds (index_rescan, code_search, docs_search) gets 3 s to finish and is answered as an ordinary tools/call result if it does; only a call still running after 3 s returns a pollable task handle (tasks/get). Clients that did not declare the extension always get the synchronous result.

  • limit: per-tool default. code_symbols, code_grep and code_refs default to 100, code_outline to 500, find_files to 200, git_log to 20, code_search and docs_search to 10.
  • max_tokens: a token budget for the returned list, default 6000. Entries are kept in result order until the budget is hit; the response then carries budgeted: true and a next_cursor.
  • cursor: opaque token; pass a response’s next_cursor back to continue.

For index scans (code_refs), basemind bounds work on common names with scan_cap = limit * 8 (at least 2000).

The server warms the code map in the background after answering the MCP handshake. While it isn’t fully ready, index_status and every code read tool may include a notice object instead of, or alongside, their normal result:

Field Meaning
state One of warming_up, building_index, rescanning, index_rebuilding, empty_index.
message Human/agent-readable explanation of what’s happening.
retry true to retry shortly for complete results; false if the result is usable but may be stale.

index_status additionally reports warming / warm_ms (in-memory preload of an existing index) and indexing / index_build_ms (first-time index build). Treat an empty or partial result carrying a notice as “retry shortly,” not “no matches.” See Index lifecycle and freshness for details.