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, point VibeMap at your existing codebase. The recommended path is local-first authoring: your agent reads the whole repo and writes the spec directly, so it's grounded in all of your code (not a digest) and the LLM work runs on your own agent, not VibeMap's server.

• Author the spec directly — vibemap_create_feature, then vibemap_create_user_story and vibemap_create_acceptance_criterion for each, grounded in the real code your agent can see. This is what the wizard's spec-authoring prompt drives, and it's the highest-quality path.
• vibemap_scan_codebase — optional: a quick local file-tree to orient before authoring (nothing leaves your machine).
• vibemap_submit_code_map — submit a structural map of the codebase, rendered on the project's Codebase tab for the user to review and confirm.
• vibemap_get_code_map — read the current map (and its confirmation status) back.
• vibemap_sync_changes — report files changed since the last sync so VibeMap flags spec drift (affected units and features on the Codebase tab).
• vibemap_analyze_codebase — fallback for when you don't have a capable local agent: VibeMap runs a server-side AI pass over a ~20-file digest and creates features only (lower grounding). Your agent still authors the stories and criteria.

The easiest way to start this flow is the Connect wizard: in VibeMap choose New Project → Start from existing code. It creates the project, generates an API key, and hands you a ready-to-paste config and a spec-authoring prompt — then shows a live status timeline (connected → authoring your spec → ready) while your agent works. The one-click analyze_codebase fallback sits behind a disclosure in the same step.

Author a spec from an idea (no codebase)

The same authoring path works idea-first, with no repo to read. When a user started their project from a description and has an agent connected, VibeMap surfaces a "Prefer your own agent? Keep it on your tokens" disclosure beneath the hosted Generate button (personas, features, pages) and on the schema empty state. Your agent reads the project idea and existing spec via vibemap_get_project_context, then authors the whole graph with the same vibemap_create_* tools — grounded in the idea instead of code. This is the "bring your own agent" alternative to VibeMap generating the spec: VibeMap runs no LLM, so the work is on the user's own tokens and doesn't meter against their VibeMap budget.

Slash-command prompts

VibeMap exposes its authoring and workflow prompts as MCP prompt primitives, surfaced by Claude Code and others as /mcp__vibemap__<name>. The prompt bodies are single-sourced in components/mcp-connect/snippets.ts and expand server-side via GET /api/mcp/prompts — the npm package ships only static metadata, so the playbooks stay current without republishing the server.

author_idea / author_spec cover personas → pages in one pass; author_schema is deliberately its own command because schema is authored last and reasons over the whole spec. All MCP access — tools and prompts — is gated to Pro plans and above (enforceMcpAccess).

Setup

Fastest path: the Connect wizard (New Project → Start from existing code) generates your API key and renders this config with the key already filled in — plus a one-line claude mcp add command for Claude Code. Use the manual steps below if you're connecting an existing project or prefer to configure by hand.

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",
        "VIBEMAP_BASE_URL": "https://vibemap.ai"
      }
    }
  }
}

Getting an API key

The Connect wizard creates a key for you automatically. To create one manually:

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.