MCP server setup

Transport and trust boundary

The server speaks the MCP stdio transport (newline-delimited JSON-RPC) to a client process on the same machine and calls the engine in-process. There is no HTTP listener and no new network surface; the trust boundary is "can you start a process on this machine", the same as the CLI. It needs the same local stack as everything else: Ollama running and repositories indexed. In lite mode, search and file reads work unchanged and ask_codebase declines with an explanation instead of a grounded answer.

Because the server is in-process, it serves clients on the host where SourceVault is installed. On a shared team server, an MCP client on the server host reaches that install; tooling on other machines uses the dashboard or the signed machine API, which accepts the same named agent tokens.

Setup

Claude Code

claude mcp add sourcevault -- sourcevault mcp

Then, in any session: "use sourcevault to search my-repo for the auth middleware", or let the model pick the tools up on its own.

Any other MCP client

Configure a stdio server with command sourcevault and args ["mcp"]. To test it standalone, run sourcevault mcp in a terminal and type a JSON-RPC request; it answers on stdout.

Installs older than v1.56.0, and source checkouts

The mcp subcommand ships in v1.56.0. On an earlier Homebrew install, point the client at the server script inside the install; on a source checkout, at the script in the tree:

claude mcp add sourcevault -- node "$(brew --prefix)/opt/sourcevault/libexec/tools/mcp-server.js"   # Homebrew, before v1.56.0
claude mcp add sourcevault -- node /path/to/sourcevault/tools/mcp-server.js                        # source checkout (or: npm run mcp)

Agent identity

MCP has no wire authentication, so identity arrives as an environment variable in the client's server config. Mint a token scoped to the mcp surface and the repositories the agent may reach, then set it:

sourcevault agent mint claude-mcp --surfaces mcp --repos backend,frontend
# the plaintext token is printed once; put it in the client's server env:
claude mcp add sourcevault -e SOURCEVAULT_AGENT_TOKEN=<token> -- sourcevault mcp

The server fails closed: a token that is set but unknown, revoked, or not scoped to mcp refuses to start rather than running unattributed. A scoped agent gets agent_repo_scope errors outside its repositories, every audit record carries subject: claude-mcp, and policy rules can be written for that subject. No token keeps the older, unattributed behaviour. The Gateway page covers scopes and revocation.

Client egress

The server transmits nothing. The client you pair it with might: an MCP client forwards tool results (retrieved chunks, file contents, cited answers) into its own model context, and a cloud-backed client sends that context to its vendor. The egress is the client's, made with the excerpts you let it retrieve; it is bounded and per question, far smaller than cloud indexing, but it is not zero.

• Under a zero-egress requirement (air gap, ITAR, strict compliance), use local-model MCP clients only, such as Hermes on Ollama or any client whose model runs on the box. This is the configuration the compliance pack's verification procedure covers.
• Where cloud-assisted development is accepted, pairing with Claude Code or similar is a deliberate, visible choice, and with the audit log on every excerpt the client retrieved is on record. Content is policy-checked and redacted before it reaches the client, and therefore before the client could forward it.

Tools

All tools are annotated read-only and local. Results include structuredContent for clients on 2025-06-18 or later alongside the JSON text block older clients parse.

search_codebase is a locator. Each result carries a short preview plus the file, line range, matched symbols, and match type: enough to pick a file and aim a read_repo_file at it. include_content defaults to false; pass true to get each chunk's full text inline, at roughly eight times the tokens per result.

ask_codebase is the dashboard engine end to end: the question retrieves on its own (query only steers), bounded multi-hop and symbol-graph grounding apply, empty retrieval declines instead of guessing, answers are cached, and citations carry per-file staleness. repo_name: "*" asks across every indexed repository; that needs a Pro or higher license and is enforced inside the engine, so a client cannot bypass it.

Resources

Read-only views of the install's state, for clients that attach context by URI. Every resource read lands in the audit log exactly like a tool call.

Prompts

Prompts encode the retrieval patterns agents get wrong unaided: tool selection and query phrasing.

Protocol support

The server is dual-era per the 2026-07-28 MCP specification. Modern clients work statelessly: declare the protocol version in each request's _meta, or call server/discover first to see what the server speaks. Legacy clients (2024-11-05 through 2025-11-25) open with the initialize handshake, and the negotiated version holds for the process. Both are served concurrently by the same process; an unsupported declared version gets an error listing the supported versions, so a client can retry.

Troubleshooting

• Tool calls fail with connection errors: Ollama is down. Run the install's health check (npm run doctor on a source checkout).
• ask_codebase declines every question: the repository is not indexed or the name is wrong. Names are case-sensitive; list_repos shows the truth.
• "*" returns a license error: Multi-repo Ask is locked on this install. It is a Pro feature and is not in the trial.
• The server refuses to start with an agent token set: the token is unknown, revoked, or not scoped to mcp. Check sourcevault agent list.

The full command list, including the Hermes slash commands and the machine API, is on the commands page.