MCP Tool List Definitions

Brain serves 19 tools over one MCP endpoint. Your agent picks them on its own — this page is for the human who wants to know what it just did, or what it could do. Terse agent-facing wording lives in /brain.md; the machine-readable definition is mcp.json.

Endpoint: https://brain.levirge.com/mcp · Protocol: MCP over Streamable HTTP · Auth: OAuth on connect, bearer token as fallback.

The vocabulary first

Six words do most of the work. The tools are much easier to read once these are clear.

Vault — the unit of scoping and access. One per project, product or client. Knowledge, skills, todos and reminders all belong to a Vault, searches are scoped to it, and permission is granted on it. A team shares a Vault; personal Vaults stay private to their owner and fail closed.

Document — a captured piece of knowledge as it arrived: a note, a decision, an incident write-up, a session learning. Identical content deduplicates, so re-running an ingest is safe.

Atom — a single extracted statement — a rule, a procedure, a fact — pulled out of documents so it can be retrieved on its own rather than buried in a longer page.

Entity — a noun the knowledge base tracks: a system, a file, a person, a concept, a subject. Entities are canonical and kebab-case (levirge-search), and each carries a consolidated summary distilled from every document that mentions it, with citations back to those sources. Entities are tracked per Vault, so counts and summaries never mix across projects.

Provenance — where a statement came from and when. Every retrieved item carries its source and timestamps, which is what lets a session judge whether a two-year-old learning still binds.

Skill — a stored procedure for a recurring task, versioned and served to every connected agent as a tool. Update it once; connected agents pick it up.

---

Finding things

search_knowledge

Semantic search across the corpus, ranked by meaning rather than keywords. Returns evidence with a confidence signal and provenance on every hit. Narrow with vault, entity, tag or source; use kind to get only rules, procedures or facts. include_content and max_total_chars control how much text comes back, so a broad question doesn't blow a context budget.

Worth knowing: search has no time dimension. For "what changed since", use list_documents below.

list_documents

Browsing rather than asking — a topic-level view of what a Vault or tag actually holds, and the right tool when a search comes back low-confidence. Supports deterministic time windows: updated_after, updated_before and sort=updated_asc, with as_of and revision on the response so paging through a window stays stable while the corpus moves underneath. That is what makes "everything that landed this week" a reliable question.

get_document

The full text behind a search snippet, by id. Batch up to 20 at once. Pass lineage: true to see the fact graph around it — what updates it, what it extends, what was derived from it — which is how you check whether something has since been superseded.

get_entity

One entity's consolidated summary, its evidence, and the documents that mention it. The fastest way to answer "what do we know about this system".

list_entities

The set of nouns the knowledge base tracks, with mention counts. Filter by kind or min_mentions. Useful as a map when you don't yet know what to search for.

knowledge_graph

A bounded graph around one Vault, entity, document or query — nodes plus typed edges (contains, mentions, updates, extends, derives, retrieved, source). Vault roots come pre-clustered into communities. Node caps keep the result small enough to reason about.

get_context_pack

One compact bootstrap instead of a dozen exploratory calls: profile, relevant search results, lineage and graph for a Vault, entity, document or query. Returns JSON for machines or Markdown for a handoff. This is the "start warm" call — what an agent reads before it begins work in an area.

kb_overview

Corpus inventory: how many documents, which Vaults, which tags and entities exist. Read-only and cheap, which makes it the standard connection check.

get_vault_profile

The same idea narrowed to one Vault: document count, top entities, tag distribution. Always fresh, no model call involved.

---

Adding and correcting

add_knowledge

Capture a fact, decision or gotcha as Markdown — one, or up to 50 in a batch. Identical content deduplicates on a content hash, so retries are safe. checked_against records what a fact was verified against (forgejo@12.0.4), so a later reader can judge whether it has gone stale.

mutate_knowledge

Corrections, four kinds. link records a typed edge between documents — updates supersedes, extends adds detail, derives records an inference. reassign_vault moves a misfiled document. delete is a recoverable soft-delete. demote halves a document's ranking without hiding it, for the noisy-but-worth-keeping. All queued and idempotent.

feedback

Closes the loop on a search. helpful gives a bounded ranking lift; dead_end down-ranks a plausible-but-wrong hit and feeds gap analysis. This is how the corpus learns what was worth keeping.

self_improvement

Memory hygiene. report is read-only: stale entity summaries, entities never consolidated, coverage gaps, recommended next actions. apply performs a single confidence-gated write from that report, and every attempt is logged.

---

Working, not just remembering

These are the tools that make Brain a work-continuity system rather than a store. They are the reason an agent that starts cold can recover what was happening.

work_session

Brackets a piece of work. start adopts a role and returns the overview, that role's open handoffs, readable open todos, your personal Vault profile and an optional context pack — the deliberate first call of a session. finish captures durable learnings, search feedback and outbound handoffs in one close-out.

todo

Vault-scoped "do later" records that surface at session start. Add, list, update, complete, delete, with priority and optional links to related documents. Writes need write access to the record's Vault, and a list never returns a todo from a Vault you cannot read.

reminder

A dated fact that stays out of the way until its date arrives — a certificate expiry, a renewal, a decision to revisit, a deliberately deferred cleanup. due is required and is canonicalised on the way in; an unparseable date is refused rather than stored, because a reminder that silently never fires is worse than none. list returns what is overdue or due now, within_days=30 looks ahead, and links point the reminder at the documents whose claim expires, so what surfaces is the knowledge and not just a nudge.

The distinction from todo is the point: a todo is work owed now; a reminder is owed later and is structurally invisible until then — not by a filter someone has to remember, but because the surfaces that list todos cannot return reminders at all.

One honest limit: Brain answers what is due; it does not notify. Nothing here emails, pushes or wakes anything. A reminder becomes due and waits to be asked about. That is deliberate — the consumer is a scheduled task you define, which queries and then decides what to do, so "tell me what's due this week" and "if the certificate expires within 30 days, open the renewal PR" are the same query with different judgement attached.

handoff

Durable agent-to-agent messaging, 30-day retention. send and reply between role identities (reviewer@brain, with an optional :instance suffix for parallel copies), inbox to check mail, wait to long-poll. Handoffs that arrive while a watcher is down are delivered on its next wait, so gaps are safe.

skill

list to browse stored skills, get to load one's full instructions, read_file to pull a bundled asset it references. Skills are versioned; the agents connected to your workspace pick up an update without redeploying anything.

create_api_token

Mints a bearer token for your user, for processes that reach Brain over HTTP rather than through an MCP session — a CI job, a cron task, a script on another machine. Shown once, unrecoverable; list and revoke them in Settings. Only the hash is stored.

---

Getting connected

Add the endpoint to your client, authenticate with OAuth, then call kb_overview to confirm the connection — it is read-only and returns your workspace's summary.

{ "mcpServers": { "brain": {
    "type": "streamable-http",
    "url": "https://brain.levirge.com/mcp" } } }

Per-client instructions, including Claude Code, Claude Desktop, Codex and Obsidian, are on the Brain page. Access is granted per workspace — request access.

One caveat worth knowing when a tool looks like it is missing an option: MCP clients cache the tool list from connection setup. If Brain ships a new parameter while your session is open, your client will keep showing the old schema until it reconnects. Restart the connection before concluding a capability isn't there.