--- generator: "vaultspec-marketing discovery" title: "Use vaultspec-rag with MCP clients - vaultspec-rag documentation" description: "An assistant like Claude Desktop or Claude Code can search your source code, and the decision records in your .vault/ directory, without you switching…" url: "https://vaultspec.neve.md/docs/rag/mcp.html" component: "vaultspec-rag" source_repository: "https://github.com/nevenincs/vaultspec-rag" source_path: "docs/mcp.md" source_commit: "ff281ac4c327a761a9bcd9edff78f55246952ba0" date_modified: "2026-10-06T13:30:20+02:00" --- [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** ```bash 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** ```bash 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** ```json { "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** ```json { "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** ```json { "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** ```bash command -v vaultspec-search-mcp ``` On Windows PowerShell: **Command** ```powershell Get-Command vaultspec-search-mcp ``` On Windows Command Prompt: **Captured output** ```text where.exe vaultspec-search-mcp ``` Then confirm the service is running: **Command** ```bash 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 ` 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** ```bash 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 ` 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.