MCP

When you need it

Working alone in one repo with an AI tool that can read your files, such as Claude Code, Codex, or Cursor, you can skip MCP. The agent files VibeCompass writes tell your AI where everything is, and it reads the rest of your project memory itself.

MCP starts to matter when:

• You want structured answers, like “what have we decided about billing?”, instead of your AI searching through decisions/*.md. What a Local answer includes is under What Local mode returns.
• Your project memory lives in the hosted app. Your AI can’t read files that aren’t on your machine, so MCP is the bridge.
• You want your AI to record decisions or session summaries through tool calls. That needs a hosted API key, and it writes to the hosted project, not your local files.

Local, Hosted, and Hybrid

You don’t pick a mode by name. The server works it out from the settings you give it when it starts: a path to your memory folder, a hosted API key, or both.

The settings go in the env block of your tool’s MCP config. Create an API key on your project’s Setup page in the hosted app. It isn’t the same as the sync token vibecompass login keeps for push.

# Local: read your files
"env": { "VIBECOMPASS_ROOT": "/absolute/path/to/.compass" }

# Hosted: read and write the hosted project
"env": { "VIBECOMPASS_API_KEY": "your-api-key", "VIBECOMPASS_API_URL": "https://vibecompass.dev" }

# Hybrid: read your files, write to the hosted project
"env": {
  "VIBECOMPASS_ROOT": "/absolute/path/to/.compass",
  "VIBECOMPASS_API_KEY": "your-api-key",
  "VIBECOMPASS_API_URL": "https://vibecompass.dev"
}

A complete Local config, for a project’s .mcp.json or Cursor’s settings

{
  "mcpServers": {
    "vibecompass": {
      "command": "npx",
      "args": ["-y", "@vibecompass/vibecompass-mcp"],
      "env": {
        "VIBECOMPASS_ROOT": "/absolute/path/to/.compass"
      }
    }
  }
}

The same thing from the Claude Code terminal

claude mcp add --transport stdio vibecompass \
  --env VIBECOMPASS_ROOT='/absolute/path/to/.compass' \
  -- npx -y @vibecompass/vibecompass-mcp

Codex uses TOML, not JSON: add this to ~/.codex/config.toml

[mcp_servers.vibecompass]
command = "npx"
args = ["-y", "@vibecompass/vibecompass-mcp"]
env = { VIBECOMPASS_ROOT = "/absolute/path/to/.compass" }

Tools by mode

Your AI tool sees only the tools its mode offers. You don’t call them yourself: your AI picks one when it needs to know something.

What Local mode returns

Local mode reads the same files you do and answers in the same shape as the hosted app, with the same size limits. A few answers differ, and each one says so in a note.

Writing back

• Write tools appear only when the server has an API key, in Hosted or Hybrid mode. Local mode never writes.
• Every write goes to the hosted project. In Hybrid mode a decision your AI logs over MCP doesn’t show up in your local decisions/ files. It reaches them only if you bring it back as a proposal.
• Decisions can’t be edited or deleted over MCP. A change of mind is a new decision.
• To add a decision to your local files, ask your AI to write it there, or use append-decision, which numbers it for you.

Session brief over MCP (opt-in)

When your memory folder’s project.yaml turns the session brief on, Local and Hybrid mode add one more tool, get_brief. It returns the same brief that vibecompass brief prints for a task, then a short summary of it as data.

# .compass/project.yaml
brief:
  enabled: true

• Your AI describes the task, and can add the files, features, and lane it’s about. It never guesses a lane: without one, the brief has no lane details.
• A brief is longer than other answers: about 6,000 tokens at most by default. Your AI can ask for a smaller one, down to about 800.
• It never hands back an old brief. If building one fails or takes more than 5 seconds, the call returns an error, and the other tools keep answering.
• It isn’t offered in Hosted mode, or when the setting is missing or set to anything but true.

What a brief is, and why it’s off by default, is on the Concepts page; what its status means, on the Protocol page; the other brief settings, on the CLI page.

Restart after a change

The server reads its settings once, when it starts. After any of these changes, restart it: in most tools, restart the AI tool or reconnect its MCP servers.

• You made the hosted app your source of truth (promote-hosted): add VIBECOMPASS_API_KEY and remove VIBECOMPASS_ROOT.
• You moved it back to local files (demote-hosted): set VIBECOMPASS_ROOT again. Keep the API key if you still want Hybrid write-back.
• You turned the brief on or off: the tool list changes at the next start. Until then, a brief turned off returns a note and builds nothing.
• You upgraded the server, or changed the version your config pins, such as @vibecompass/vibecompass-mcp@0.1.8.

When something is slow or offline

A VibeCompass tool never crashes your session. Requests to the hosted app use a 5-second timeout. A read that fails answers from what it last read in this session, or with an empty answer, and the server keeps going. Reads from your own files have no hard limit: on a very large project one can take longer than 5 seconds, and other calls wait for it. Two kinds of call return an error instead of an old or empty answer: the session brief, which stops building at 5 seconds, and a write that wasn’t confirmed. A write error doesn’t always mean nothing was saved, so check the dashboard before trying again, or the same decision can be recorded twice.