Docs/Connecting to Minerva/MCP use
MCP use
The Model Context Protocol (MCP) is a standard way to give an AI agent tools. Minerva's MCP server exposes the same reads and proposals as the CLI — as tools any MCP client can call — so an agent like Claude Desktop, a coding agent, or an editor can ground itself in your thoughtbase and hand work back through the approval gate.
This page is Minerva as an MCP server: your thoughtbase goes out to an outside agent. If you want the reverse — connecting Minerva to somebody else's MCP server, so its tools are available to Minerva's own assistant while you chat — that's Settings → MCP Servers. The two are independent and can run at the same time.
Starting the server
The MCP server is the mcp subcommand of the same CLI — install it once (on macOS, Help → Install ‘minerva’ Command in PATH…; on other platforms, build it from the source tree) and you have the minerva command. The server runs over standard input/output as a subprocess — you don't start it by hand so much as tell a client how to launch it. On its own:
minerva mcp --project /path/to/thoughtbaseIt speaks newline-delimited JSON-RPC 2.0 and stays running until its input closes. Each modality initializes once and stays warm across tool calls.
Connecting a client
Most MCP clients take a small JSON entry naming a command to launch. Point it at minerva with the mcp subcommand and your thoughtbase path — the client runs it as a subprocess:
{
"mcpServers": {
"minerva": {
"command": "minerva",
"args": ["mcp", "--project", "/path/to/thoughtbase"]
}
}
}Some clients — Claude Desktop among them — launch from a bare environment without your shell's PATH, so minerva may not resolve. If so, give the full path to the launcher instead. The install dialog shows it: ~/.local/bin/minerva, spelled out from your home folder, since a client won't expand ~ for you:
{
"mcpServers": {
"minerva": {
"command": "/Users/you/.local/bin/minerva",
"args": ["mcp", "--project", "/path/to/thoughtbase"]
}
}
}Running from a source checkout instead? There's no launcher, so have the client run the built file with Node: "command": "node", with "/absolute/path/to/minerva/.vite/build/cli.js" as the first argument ahead of "mcp".
Tools
The server exposes eight tools — the reads return grounded JSON, and the one write is gated:
query_graphsql_querysearch_notesgrep_notesgrep — a literal string by default, or a regular expression with regex; case_sensitive and limit (default 50, at most 200) are optional. Returns the path and line of each match, so it suits a known phrase, a pattern such as unfinished - [ ] tasks, or checking whether something appears at all.semantic_searchread_note.minerva/ and other hidden folders are refused.gather_contextpropose_notenote summary that's shown in the review queue.An outside agent reads your notes, and a note — especially one someone shared with you — can contain text written to steer whatever reads it. So the tools hold the line regardless of what the agent asks for: read_note won't open anything in .minerva/ (your conversations, settings and stored keys) or any other hidden folder; sql_query sees only the tables Minerva registered and can't read files by path — SHOW TABLES lists them and DESCRIBE <table> shows a table's columns; and propose_note can't target those folders or anything outside the thoughtbase. The same reads typed in your own shell — minerva read, minerva sql — aren't restricted this way, because you wrote them.
Reads come back grounded, so the agent can cite the exact notes it drew on. The only write is propose_note, which files a pending proposal stamped mcp:<client-name> — taken from the client's own name at connect time — and nothing lands until you approve it in the Proposals panel. In Minerva, proposals from an MCP client are labelled distinctly from the built-in AI, so the graph stays an audit log of who contributed what. See Conversations.
A note on freshness
The server notices on its own whether Minerva has the same thoughtbase open (the app leaves a .minerva/runtime.json marker while it does), and acts differently:
propose_note and semantic_search are handed to the running app. A proposal goes through the app's own approval gate and appears in the Proposals panel right away; semantic search uses the app's current index.Either way, read_note and grep_notes read the files as they are now. The knowledge graph, full-text index and tables behind query_graph, search_notes, sql_query and gather_context are loaded the first time a tool needs them and kept for the rest of the session, so restart the server to pick up notes edited since.