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.

Starting the server

The MCP server is the mcp subcommand of the same CLI — install it once (Help → Install ‘minerva’ Command, or build from source) 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/thoughtbase

It 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 launch from a bare environment without your shell's PATH, so minerva may not resolve. If so, give the absolute path to the built file instead:

{
  "mcpServers": {
    "minerva": {
      "command": "node",
      "args": ["/absolute/path/to/minerva/.vite/build/cli.js", "mcp", "--project", "/path/to/thoughtbase"]
    }
  }
}

Tools

The server exposes seven tools — the reads return grounded JSON, and the one write is gated:

query_graph

SPARQL over the knowledge graph.

sql_query

DuckDB SQL over your CSV tables.

search_notes

Full-text search over notes.

semantic_search

Meaning-based search over notes the app has embedded.

read_note

A note's raw markdown, by path.

gather_context

A topic slice — matching notes plus their link neighborhood — for the agent to seed itself.

propose_note

File a new note as a pending proposal (gated).

Grounded and gated

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 reads your thoughtbase once at startup and serves results as of that moment. If you edit notes in the app while it's running, restart the server to pick up the changes. And as with the CLI, file proposals when the app isn't actively editing the same thoughtbase, so the two aren't writing the graph at once.

⌥

CLI use

The same operations from your shell, as JSON.

💬

Conversations

Review and approve what an agent proposes.