5.1 — MCP server overview

The VibeMap MCP server is what connects your IDE's AI agent directly to your VibeMap project. Once it's set up, your agent can:

• List and inspect your projects
• Read features, user stories, acceptance criteria, personas, pages, and schema
• Claim a "next ready" acceptance criterion, work on it, and submit the result
• Update kanban status as the work moves through review

It's published as @vibemap.ai/mcp-server on npm and installs via your IDE's MCP configuration in about five minutes.

📸 Placeholder: 18-mcp-server-flow.png — diagram of "IDE → MCP server → VibeMap" with examples of tool calls flowing each way.

What's new in v2.1

vibemap_get_atomic_blueprint — a single-call, code-shaped projection of your entire project spec. Instead of assembling context from multiple tool calls, this returns entities, interactions, page auth rules, roles, and navigation in one deterministic payload tuned for LLM coders. See the tools reference for the full schema.

Supported IDEs

Any other MCP 0.3+ compatible client should also work.

What it can do

Pull spec from VibeMap into your IDE

This is the main flow. Your agent reads from your spec to know what to build:

• Load features and their descriptions as context
• Pull acceptance criteria for whatever you're about to implement
• Reference user stories and personas while coding

Update VibeMap from your IDE

Your agent reports back as it works:

• Claim an AC so other windows/sessions don't double-claim it
• Stream progress updates (visible on the Track tab in real time)
• Submit work for review with a git SHA + diff URL
• Mark an AC blocked with a category + reason if it can't proceed

Reverse-engineer existing code

If you've already started building, you can also point VibeMap at an existing codebase:

• vibemap_scan_codebase — scan a local repo
• vibemap_analyze_codebase — submit it for AI analysis
• Generate features, user stories, and acceptance criteria from what already exists

Setup

Add the following to your IDE's MCP configuration file:

{
  "mcpServers": {
    "vibemap": {
      "command": "npx",
      "args": ["-y", "@vibemap.ai/mcp-server@latest"],
      "env": {
        "VIBEMAP_API_KEY": "vm_your_key_here"
      }
    }
  }
}

Getting an API key

1. In VibeMap, click your avatar → Account.
2. Scroll to API Keys and click Generate New Key.
3. Copy the key (it starts with vm_) — you won't be able to see it again.
4. Paste it into the config above and restart your IDE.

Verifying the connection

After configuring your IDE and restarting it, the VibeMap tools should appear in your IDE's MCP tool list. The quickest test is to ask your agent:

"List my VibeMap projects."

If you see your projects come back, you're set. If not, see Troubleshooting in the Getting Started guide.

Authentication

The MCP server authenticates using your API key, passed via the VIBEMAP_API_KEY environment variable in the MCP config. All requests are scoped to the key owner's projects — the server can't accidentally read or write someone else's data.

How it works (high level)

Your IDE  <--->  MCP Server (local Node process)  <--->  VibeMap API (vibemap.ai)

The MCP server runs as a local process spawned by your IDE. It translates MCP tool calls into VibeMap API requests and returns structured results back to the IDE. You don't need to start or stop it manually — your IDE handles its lifecycle.

Where to go next

→ 5.2 — Tools reference — every tool the MCP server exposes, with parameters and example responses.