Connect your IDE

Wire your AI coding agent to VibeMap over MCP — one config block, one API key, one restart. · Required

Connecting your IDE is the bridge between your VibeMap spec and your agent. It's a one-time setup per IDE per machine. The same MCP connection powers both directions: your agent reading the spec to build it, and — for existing code — syncing your codebase back into VibeMap.

MCP access itself is on every plan, free included. What your plan changes is which parts of the spec your agent may author over that connection — see Two ways to generate.

What you need first

• An API key. Your agent authenticates with a vm_ personal access token. Create one at Account → Developer → Generate Key and copy it — it's shown once.
• An IDE with MCP support — Claude Code, Cursor, Windsurf, or VS Code with Copilot.

The guided connect wizard (fastest)

For the smoothest path, VibeMap has a guided Connect wizard. You give your project a name, and the wizard:

1. Creates the VibeMap project and an API key for you.
2. Renders a connection kit with your key already embedded — pick your IDE (Claude Code, Cursor, or Windsurf) and copy the ready-to-paste config.
3. Shows a live status panel that lights up as your agent connects and starts working — waiting → connected → authoring your spec → ready.

Figure: The guided connect wizard's connection kit.

The wizard is also the entry point for reverse-engineering an existing codebase — see Codebase sync & code map. For a project that already exists, the same material is one click away inside it: Use in IDE in the project sidebar carries the project id and paste-ready prompts, and the ⓘ Handoff Instructions panel on the Development board carries the MCP config and your API-key status.

Manual setup

If you'd rather configure by hand, add this block to your IDE's MCP config file, replacing the placeholder with your key:

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

Where that file lives, per IDE:

⚡ Power user: On Claude Code you can skip the JSON entirely and run one command:

claude mcp add vibemap -s user -e VIBEMAP_API_KEY=vm_your_token_here -e VIBEMAP_BASE_URL=https://vibemap.ai -- npx -y @vibemap.ai/mcp-server

Keep the -s user — it registers the server at user scope, so vibemap loads in every Claude Code session instead of only the directory you ran the command in.

⚠️ Watch out: If the config file lives inside a project folder (Cursor, Windsurf, VS Code), it contains your API key — add it to .gitignore so you don't commit the token.

Restart and verify

MCP config is only read on startup, so fully quit and reopen your IDE (not just close the window).

Then confirm the connection:

1. Look for the IDE's own signal — Claude Code's hammer icon, or vibemap showing connected in Cursor/Windsurf's MCP server list.
2. Ask your agent: "List my VibeMap projects." If they come back, you're connected.

If the guided wizard is open, its live-status panel confirms the connection for you automatically.

⚠️ Watch out: VibeMap is a cloud app — it can't read your IDE's local config file, so it can't verify the MCP step for you. The real proof is your agent successfully calling a VibeMap tool and a card moving on the Development board.

⚡ Power-user hints

• One key, many IDEs. The same vm_ token works across every machine and editor — or create a dedicated key per agent so you can revoke one without disturbing the rest.
• Account → MCP is the reference card. It renders the config per IDE (Claude Desktop, Cursor, Windsurf) plus a first prompt to paste, and lists which of your keys have been used recently. It can't fill the token in for you — full tokens are shown once, at creation — so paste yours over the vm_your_token_here placeholder. The guided wizard does embed a real key, because it just created it.
• Kill switch. Revoking the key from Account → Developer stops any connected agent cleanly on its next call.

↔ The traditional way

Traditionally you'd email a spec to a contractor and hold a kickoff call to brief them, then rely on them to keep their local work aligned with a document that's already drifting. Connecting your IDE replaces that with a persistent, machine-readable link: your agent reads the live spec on demand and reports back onto a shared board — no re-briefing, no reconciliation.

What's next

• Point your agent at the project and watch it build → Watching progress
• Sync an existing codebase into VibeMap → Codebase sync & code map
• Connection not working? → Troubleshooting