---
generator: "vaultspec-marketing discovery"
title: "Connect your agent - Vaultspec documentation"
description: "Core exposes project operations through the Model Context Protocol (MCP). Your coding agent calls these tools to find records and report progress."
url: "https://vaultspec.neve.md/docs/guides/mcp.html"
component: "site"

---

[View as Markdown](<https://vaultspec.neve.md/docs/guides/mcp.md>)

# Connect your agent

Core exposes project operations through the Model Context Protocol (MCP). Your coding agent calls these tools to find records and report progress.

## Point your agent at it

Complete the [Core installation](<https://vaultspec.neve.md/docs/core/installation.html>) in your project, then open that project in your agent. The default installation writes Core’s server entry to these locations:

| Agent | Generated MCP configuration |
| --- | --- |
| Claude Code | `.mcp.json` |
| Codex | `.codex/config.toml` |
| Antigravity | `.agents/mcp_config.json` |

Gemini receives workflow guidance, but this installation does not generate a native Gemini MCP entry. Use the [command-line guide](<https://vaultspec.neve.md/docs/guides/cli.html>) when your agent has no Core MCP tool. The prompt walkthrough here was tested with Codex.

For example, the generated `.mcp.json` entry is:

**File contents**

```json
{
  "mcpServers": {
    "vaultspec-core": {
      "command": "uvx",
      "args": ["--from", "vaultspec-core", "python", "-m", "vaultspec_core.mcp_server.app"]
    }
  }
}
```

This is generated configuration, not another setup step to copy. A `dev` or `dependency` [installation](<https://vaultspec.neve.md/docs/core/installation.html#choose-a-provisioning-mode>) launches the server with `uv run --no-sync` from the project environment instead.

Your agent must enable and trust the server according to its own controls. The installer does not grant that trust.

## Check that it connected

After the [quickstart](<https://vaultspec.neve.md/docs/index.html>), send:

**Prompt for your agent**

```
Use the vaultspec-core MCP status tool to show the status of this project. Tell me which features exist and whether any plan is in flight. Do not change any files.
```

The tested Codex session called Core’s `status` tool and reported `notes-search` with one research record and no plan. Inspect the tool call as well as the reply: the reply should be based on the project’s current state.

If the agent cannot find the tool, check that it opened the right project and enabled the configured server. Compare the result with:

**Command**

```sh
uvx vaultspec-core status
```

If terminal commands are blocked, check the agent’s permissions separately from its MCP connection.

## Two products, one file

Core manages records; vaultspec-rag searches them and your code. In a project with Core installed, vaultspec-rag’s setup writes a `vaultspec-rag` entry beside Core’s. Keep both.

That entry launches a small server that forwards each search to the machine’s vaultspec-rag service. Searches need that service running and the project indexed; follow [vaultspec-rag setup](<https://vaultspec.neve.md/docs/rag/installation.html>) and [how vaultspec-rag runs](<https://vaultspec.neve.md/docs/guides/rag-service.html>).

## Where to go next

For the complete tool set and read-only server options, see the [Core MCP reference](<https://vaultspec.neve.md/docs/core/mcp.html>). For key resolution and environment sources, see [TypeSafe and environment loading](<https://vaultspec.neve.md/docs/guides/typesafe-env.html>).

Continue with [Run a feature](<https://vaultspec.neve.md/docs/guides/workflow.html>) once the status check works.