1.4 — Connect your AI coding agent
On this page
1.4 — Connect your AI coding agent
VibeMap ships an MCP (Model Context Protocol) server that lets your IDE's AI agent talk directly to your project — pulling specs, claiming work, and reporting progress. This is what turns a spec in VibeMap into actual code in your editor.
Supported IDEs:
- Cursor
- Claude Code (terminal and IDE extensions)
- Windsurf
- VS Code (with the Copilot or Continue extensions)
- Any other MCP-compatible client
This page is the 5-minute version. The Kanban Tracker user guide covers the day-to-day flow in detail.
Step 1 — Generate an API key
- In VibeMap, click your avatar (top-right) → Account.
- Scroll to API Keys.
- Click Generate New Key.
- Copy it now — you won't be able to see it again. Store it in a password manager.
📸 Placeholder:
08-api-key-manager.png— the API Keys section of the Account page.
Treat this key like a password. Anyone with it can read and write to your VibeMap projects.
Step 2 — Find your IDE's MCP config file
| IDE | Config file location |
|---|---|
| Cursor | ~/.cursor/mcp.json (global) or <project>/.cursor/mcp.json (per-project) |
| Claude Code | ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) |
| Windsurf | ~/.codeium/windsurf/mcp_config.json |
| VS Code (Continue) | ~/.continue/config.json |
If the file doesn't exist, create it.
Step 3 — Paste this configuration
{
"mcpServers": {
"vibemap": {
"command": "npx",
"args": ["-y", "@vibemap.ai/mcp-server@latest"],
"env": {
"VIBEMAP_API_KEY": "your-api-key-here"
}
}
}
}
Replace your-api-key-here with the key from Step 1.
Step 4 — Restart your IDE
MCP servers load at IDE startup. A reload of the window is usually enough; sometimes a full quit + relaunch is needed.
Step 5 — Verify the connection
Open a new chat in your IDE and ask:
"List my VibeMap projects."
Your agent should call the vibemap_list_projects tool and return your project list. If it doesn't, see Troubleshooting below.
📸 Placeholder:
09-mcp-verify.png— IDE chat showingvibemap_list_projectsresults.
What your agent can now do
Once connected, your agent has access to ~25 tools for reading and writing to your project. The most important ones:
| Tool | What it does |
|---|---|
vibemap_list_projects | List all your projects |
vibemap_get_atomic_blueprint | Pull a one-shot, code-ready projection of an entire project spec |
vibemap_get_next_ready_criterion | Find the next acceptance criterion ready to work on |
vibemap_claim_criterion | Claim it so you don't double-up with another window |
vibemap_report_progress | Stream progress updates back to VibeMap (visible on the Track tab) |
vibemap_submit_for_review | Submit your work + git SHA + diff URL |
vibemap_block_criterion | Mark a criterion blocked with a category + reason |
Full tool reference: 5 — MCP server.
Troubleshooting
"My agent doesn't know about VibeMap." The MCP config file path or JSON is wrong. Double-check the location for your IDE and that the JSON parses.
"Authentication failed." The API key was copied incorrectly (often a stray space or missing character). Regenerate and try again.
"The tool list is empty." You're probably running an old MCP client. Confirm your IDE supports MCP 0.3+ — Cursor and Claude Code do; older Continue versions don't.
"It worked yesterday, now it doesn't."
First check npx works in your shell — sometimes a system update breaks Node. Run npx -y @vibemap.ai/mcp-server@latest --version directly to see the failure.
Where to go next
- Learn what VibeMap generates and why → 2 — Core concepts
- Walk through your first agent-driven build → 6.2 — Kanban tracker user guide
- Browse the full MCP tool reference → 5.2 — MCP tools reference