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.

What you need first

• An API key. Your agent authenticates with a vm_ personal access token. Create one at Account → Developer → Generate New 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 (Pro+). 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 → analyzing → complete.

The wizard is also the entry point for reverse-engineering an existing codebase — see 12.1 Codebase sync & the code map. For an already-built spec, the same connection kit is available on the Hand off tab of the Development page.

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 -e VIBEMAP_API_KEY=vm_your_token_here -e VIBEMAP_BASE_URL=https://vibemap.ai -- npx -y @vibemap.ai/mcp-server

⚠️ 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 Track 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.
• The MCP tab pre-fills your key. Account → MCP renders the per-IDE config with your key already substituted.
• 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 → 11.3 Watching progress
• Sync an existing codebase into VibeMap → 12.1 Codebase sync & the code map
• Connection not working? → 11.4 Troubleshooting