Copy page View as Markdown

Use vaultspec-rag with MCP clients

An assistant like Claude Desktop or Claude Code can search your source code, and the decision records in your .vault/ directory, without you switching tools. The Model Context Protocol (MCP) is a JSON-RPC interface assistants use to call external tools, and vaultspec-rag ships an MCP server that exposes its search and indexing operations as MCP tools. Any client that speaks stdio MCP can connect.

This page assumes you have installed vaultspec-rag and run at least one search. See the installation guide for setup and the getting-started tutorial for the first-search path.

Examples use the installed-tool form and call vaultspec-rag directly. If vaultspec-rag is a project dependency, prefix each command with uv run; see the installation guide for lane selection, including the standalone tool and no-install routes.

Install the MCP server

vaultspec-rag install enrolls the MCP server by default and writes the client configuration for you. When vaultspec-rag is a project dependency, it also adds the optional mcp extra to that requirement; run uv sync afterwards, because the written configuration launches the server without syncing:

Command

vaultspec-rag install

The server publishes six index-mutating tools. Four reindex, and two delete indexes: clean_documents deletes the extracted-document index, and clean_all deletes every index for the project. If you want the assistant to search and nothing else, see Withholding the mutating tools before you connect a client.

Use --no-mcp for a CLI-only workspace, which also skips the mcp dependency and, on Windows, pywin32.

Prefer vaultspec-rag install over hand-writing the config. --mode selects the launch shape: tool (launched via uvx, and used when neither a recorded mode nor the project’s dependencies say otherwise), dependency (resolved through the project’s own virtual environment and shipped in built distributions), or dev (like dependency, but confined to the dev dependency group). server doctor compares the shape in your config against the declared mode, so a hand-written entry that disagrees with the mode shows up as a failing check.

The vaultspec-search-mcp console script is registered by the base install, but it needs the mcp extra to run. Without it the server exits at launch with a message naming the fix. The server loads no models, so vaultspec-rag[mcp] is all a client installation needs; vaultspec-rag[gpu,mcp] installs the MCP protocol and the local inference stack together for a host installation.

Start the service

Start the service from the host installation before connecting an assistant:

Command

vaultspec-rag server start

Check the client sees it

In Claude Desktop, open the MCP debug panel and look for the vaultspec-rag server. In Claude Code, run /mcp and check that vaultspec-rag appears in the connected-servers list.

Then ask the assistant a retrieval question about your project, such as “find the decision record about caching” or “where is authentication handled?”. A successful answer cites locations from your project, a document path or a source file and line, rather than answering from general knowledge.

How the connection works

MCP reaches vaultspec-rag over stdio only. The client launches vaultspec-search-mcp as a child process, and that stdio server reads the project from VAULTSPEC_RAG_ROOT, falling back to the framework-wide VAULTSPEC_TARGET_DIR when unset - the same variable a session might already export for another vaultspec tool. It loads no models: it forwards every call to the HTTP service, which does the compute and serves several projects at once. Because the service is multi-tenant, the stdio server tags each forwarded call with the project root it resolved.

The HTTP service does not speak MCP. It serves only vaultspec-rag’s own REST routes, which are the operator and monitoring surface covered in the service-mode guide. No MCP client connects to them directly.

Passing --port does not serve MCP over HTTP. It starts the REST service daemon instead, which is what server start launches. Leave --port off for MCP.

The tools

A connected server publishes twelve tools. Six read:

• search_vault searches the documentation vault, with the same filters as the search command (doc type, feature, date, tag) plus an intent ranking profile.

• search_codebase searches source code, with the code filters (language, path, symbol, include and exclude globs) plus controls to include or exclude whole classes of files such as tests, generated code, and vendored trees, through the exclude_domains, only_domains, and include_domains arguments. See Filter noise by domain.

• search_documents searches extracted documents, meaning preprocessed non-source content, as an independent domain.

• search_combined defaults to relevant ADRs and code, ranked together. Set include_documents=true to search all three domains and all vault record types. Explicit doc_type or inline type:plan overrides the ADR default. Each search response includes an advisory with MCP filter syntax and points to source and doc_type for verifying result kinds.

• get_code_file returns the full content of a source file by path. It returns only files the code index admits: a path that is ignored, is not source, or has a dot-prefixed file or directory name anywhere in it is refused with access denied, as is a file whose name suggests keys or credentials.

• get_index_status reports whether a content kind is indexed, so an assistant can skip one that has no index. It also returns the running service’s installation (whether it can run inference, and on what hardware) and the project’s active features: preprocessing hooks and the file watcher.

Six mutate:

• reindex_vault, reindex_codebase, and reindex_documents re-index one domain incrementally, and reindex_all does all three.

• clean_documents deletes the extracted-document index for a project, and clean_all deletes the vault, code, and document indexes.

The search filters mostly mirror the CLI, so the CLI reference documents their values. Three parameters do not appear there, and a client written from the CLI alone will miss them. The result count is top_k, where the CLI spells it --max-results; the default is 10 either way. And like_ids and unlike_ids take point ids from earlier results and steer the dense half of the query toward or away from them, which the CLI has no flag for at all. Feedback ids are accepted by search_vault and search_codebase only: search_documents and search_combined refuse them with unsupported_feedback_for_search_type, because their results carry no cross-collection point identity to resolve the ids against.

Service administration is not exposed over MCP: jobs, logs, project slots, the file watcher, service state, and starting or stopping the service all go through the vaultspec-rag server CLI.

Withholding the mutating tools

clean_all deletes every index for the project, and an assistant that can see a tool will eventually call it.

Where the flag goes depends on who owns the file. On a project with vaultspec-core installed, .mcp.json belongs to its installer, which has already written an entry for this server: add --read-only to that entry rather than replacing it; the edit persists across syncs. The shape below is for a client you configure yourself, and Configure a client by hand covers both cases in full.

Launch with --read-only to serve only the six read tools:

File contents

{
  "mcpServers": {
    "vaultspec-rag": {
      "command": "vaultspec-search-mcp",
      "args": ["--read-only"],
      "env": {
        "VAULTSPEC_RAG_ROOT": "/absolute/path/to/your/project"
      }
    }
  }
}

The six mutating tools are withdrawn from the advertised listing rather than refused on call, so the model is never handed the schema of something it cannot use. Reindexing then happens through the CLI, or through the service’s own watcher, which keeps the index current without being asked.

Configure a client by hand

install does not write configs for every client. If yours is one it misses, copy an example below. Both use the console-script shape, which runs wherever vaultspec-search-mcp is on your PATH - a standalone tool install or a prebuilt binary. It is not what the installer writes for tool mode: that renders uvx --from vaultspec-rag[mcp] python -m vaultspec_rag.server, which fetches the mcp extra rather than requiring it to be installed already. The server loads no models and forwards every call to the service, so that launch never pulls the inference stack, whichever extras you installed with. For dependency or dev mode, set command to uv and args to ["run", "--no-sync", "python", "-m", "vaultspec_rag.server"].

Add "args": ["--read-only"] to either example to withhold the mutating tools.

Every example below sets the project root through VAULTSPEC_RAG_ROOT in the launch entry’s own env block, the most explicit choice for a config a client owns outright. An unmanaged client that instead inherits its environment from a session already exporting the framework-wide VAULTSPEC_TARGET_DIR needs no entry of its own: the stdio server falls back to that name when VAULTSPEC_RAG_ROOT is unset.

Claude Desktop

Claude Desktop reads its MCP config from claude_desktop_config.json. The location varies by operating system; open Claude Desktop’s settings dialog to find the path on your machine.

Add a vaultspec-rag entry under mcpServers and set VAULTSPEC_RAG_ROOT to the absolute path of the project you want the assistant to search:

File contents

{
  "mcpServers": {
    "vaultspec-rag": {
      "command": "vaultspec-search-mcp",
      "env": {
        "VAULTSPEC_RAG_ROOT": "/absolute/path/to/your/project"
      }
    }
  }
}

Restart Claude Desktop after editing the file.

Claude Code

Claude Code reads .mcp.json at the project root. Check whether one is already there before you write it.

Warning. On a project where vaultspec-core is installed, .mcp.json belongs to its installer, which has written an entry for this server already. Keep the written one. To withhold the mutating tools from an installed project, add --read-only to the entry that is already there rather than replacing it. Pasting the block below over it does not hold. Use this block only where nothing has written the file for you:

File contents

{
  "mcpServers": {
    "vaultspec-rag": {
      "command": "vaultspec-search-mcp",
      "env": {
        "VAULTSPEC_RAG_ROOT": "/absolute/path/to/your/project"
      }
    }
  }
}

Troubleshooting

The assistant does not see the tools

Confirm the command your client launches is on the PATH the client starts with. An entry written by vaultspec-rag install launches uvx in tool mode or uv in dependency and dev mode; a hand-written entry launches vaultspec-search-mcp. Substitute the command your entry names below. On macOS or Linux:

Command

command -v vaultspec-search-mcp

On Windows PowerShell:

Command

Get-Command vaultspec-search-mcp

On Windows Command Prompt:

Captured output

where.exe vaultspec-search-mcp

Then confirm the service is running:

Command

vaultspec-rag server status

If the service is down the tools connect but every call reports that the service is not running. Start it with vaultspec-rag server start and reconnect.

If the console script is missing, or exits naming the mcp extra, the installation that provides it lacks that extra. Reinstall it with mcp added to the extras it already has, keeping a GPU tool installation’s torch pin. vaultspec-rag install adds the extra only to a project requirement in dependency or dev mode, after which you run uv sync; it never changes a tool installation’s packages.

server doctor reports an install-mode mismatch

The launch shape in your client config disagrees with the declared provisioning mode. Re-run vaultspec-rag install --mode <mode> with the mode you want, or rewrite the entry to match it. See Install the MCP server.

Results come from the wrong project

Set VAULTSPEC_RAG_ROOT to the absolute project path in the env block and restart the client. Without it the server falls back to its working directory, which rarely matches the project you want.

The first call is slow

The MCP server loads no models. The service loads them when it starts, and server start waits until they are ready. A slow first call usually means the service is still starting, or is opening that project for the first time. Check its state:

Command

vaultspec-rag server status

Process lifetime

The stdio server exits when its client does, printing one JSON line on stderr as it goes. It detects a departing client by watching the process that created its stdin pipe, so it leaves no orphaned uv -> launcher -> python chains behind on Windows when a client kills the launcher without closing the pipe. Nothing here needs configuring.

Two knobs exist for unusual setups: --parent-pid <pid> adds an explicit process to watch, and VAULTSPEC_RAG_STDIO_WATCHDOG=0 disables the self-reap.

Where to go next

• Run and supervise the service.

• Search filters and result formats.

• Commands, flags, and filter values.

If something still does not work, see Support and license in the repo README.