MCP Setup

Vreko speaks the Model Context Protocol (MCP). Once connected, your AI agent can call four Vreko tools to load codebase intelligence - fragile files, co-change patterns, AI attribution, and past learnings - directly into its session.

This page covers setup only. For what each tool does and when to call it, see the MCP Tools Reference.

100% local. The Vreko MCP server runs on your machine and talks to the Vreko service over a local socket. No code or file contents leave your device.

The four tools

Vreko exposes exactly four MCP tools, which form one session lifecycle:

Tool	When the agent calls it
`vreko`	Start of every task - loads intelligence
`vreko_pulse`	Mid-task health check (read-only)
`vreko_learn`	When it discovers something worth remembering
`vreko_end`	Task complete - closes the session

Full parameters, return shapes, and examples live in the MCP Tools Reference. The setup below wires these four tools into your editor.

Setup

The fastest path is the CLI: install it, then point your agent at the local MCP server.

npm install -g @vreko/cli
cd your-project
vr init

vr init provisions the workspace and starts the Vreko service. Then add the MCP server to your agent.

Add Vreko to your project’s .mcp.json (or ~/.mcp.json for a global setup):

{
  "mcpServers": {
    "vreko": {
      "command": "npx",
      "args": ["@vreko/cli", "mcp", "--stdio", "--workspace", "${workspaceFolder}"]
    }
  }
}

Restart Claude Code. The four Vreko tools (vreko, vreko_pulse, vreko_learn, vreko_end) appear in its tool list and can be called automatically at the start of each task.

Add Vreko to .cursor/mcp.json in your project root (or ~/.cursor/mcp.json to enable it everywhere):

{
  "mcpServers": {
    "vreko": {
      "command": "npx",
      "args": ["@vreko/cli", "mcp", "--stdio", "--workspace", "${workspaceFolder}"]
    }
  }
}

Cursor substitutes ${workspaceFolder} with the active workspace, so each window gets its own server instance. Reload Cursor to pick up the change.

Using the VS Code extension? It auto-configures MCP for the editors it detects - you usually don’t need to edit any config files by hand. See the Getting Started guide.

Verify the connection

After your agent restarts, confirm the service is running:

vr status

Then ask your agent to call the vreko tool. A healthy response returns a session with your workspace’s current intelligence (fragile files, co-change alerts, relevant past learnings). If nothing comes back, re-run vr status and confirm the service is up.

Next steps

MCP Tools Reference - what each of the four tools does
Getting Started - install Vreko and the VS Code extension
CLI Reference - drive Vreko from the terminal
Troubleshooting - common connection issues

MCP Setup

The four tools

Setup

Verify the connection

Next steps

On this page