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.
- Open the Developer tab.
- Click Generate Key and give it a name that says which machine and IDE it's for —
Cursor on work laptopbeatskey 2once you have several. - Copy it now — you won't be able to see it again. Store it in a password manager.
Treat this key like a password. Anyone with it can read and write to your VibeMap projects.
📎 The name matters more than it looks. A key is an agent identity: it shows up by name in the board's assignee picker, and work assigned to it is reserved for it. See Assigning work.
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.
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 Development board) |
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.
Author your spec with your agent
The tools above are the build side — reading a finished spec and reporting work back. The same connection also lets your agent author the spec in the first place, on your own tokens, instead of having VibeMap generate it. VibeMap runs no server-side LLM on this path; it only stores what your agent writes via the vibemap_create_* tools:
| Tool | Authors |
|---|---|
vibemap_create_persona | A user archetype |
vibemap_create_feature | A product capability |
vibemap_create_user_story | A story under a feature |
vibemap_create_acceptance_criterion | A BDD criterion under a story |
vibemap_create_page | A screen/route |
vibemap_create_schema | The whole Postgres data model, in one call |
You rarely call these by hand. VibeMap ships slash-command prompts (surfaced in Claude Code as /mcp__vibemap__<name>) whose bodies carry the full authoring playbook — coverage floors, criticality scaling, BDD discipline, and a resumable handover protocol:
| Slash command | What your agent does |
|---|---|
/mcp__vibemap__author_idea | Authors the whole graph (personas → pages) from the project idea |
/mcp__vibemap__author_spec | Same graph, grounded in your entire local codebase |
/mcp__vibemap__author_schema | Designs the database schema — a separate step, run last |
author_idea / author_spec write personas → features → user stories → acceptance criteria → pages in one pass; schema is deliberately its own step. Prompt bodies expand server-side via GET /api/mcp/prompts, and none of this spends your VibeMap token budget — your agent is running on its own.
MCP access is on every plan, free included — it is not a Pro gate. What your plan controls is which entities your agent may author: writing pages or schema over MCP needs the same pages / schema capability a hosted generation would, so those start at Starter. See the user-facing Two ways to generate.
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.1 — Kanban tracker user guide
- Browse the full MCP tool reference → 5.2 — MCP tools reference