Handoff overview

How VibeMap hands your spec to your own AI coding agent — via MCP, not a code export. · Required

New to VibeMap? Read the end-to-end walkthrough first — it strings every step together in order. This page is the how of the handoff itself.

Once your spec is in good shape and Prepare for Development is done, it's time to hand the work to your AI coding agent.

VibeMap doesn't try to be a code generator on the handoff path. Instead it connects to your agent — Cursor, Claude Code, Windsurf, or VS Code with Copilot — over the Model Context Protocol (MCP). Your agent reads the spec from VibeMap, picks the next ready acceptance criterion, implements it in your codebase, and submits the result. You (or your CI) approve, and the next AC unlocks.

💡 Tip: Prefer VibeMap to write the code for you instead of your own IDE agent? Use the App Builder — the "Build it here" path on the Development page.

The handoff is bidirectional

This isn't a one-way export. Over MCP your agent reads the spec and reports progress back: it moves cards across the kanban, leaves notes, and submits work for review. You watch it happen live on the Track tab.

Three things to set up

Everything you need lives on the Hand off tab of the Development page.

1. Generate an API key

Your agent authenticates with a personal access token. Click through to Account → Developer → Generate New Key, name it after the agent or machine, and copy it — it's shown once. The Hand off tab shows how many keys you already have.

2. Connect the MCP server in your IDE

The Hand off tab has a copy-paste MCP config block for your project (the same @vibemap.ai/mcp-server config used everywhere). Paste it into your IDE's MCP config, drop in your API key, and restart. Full per-IDE steps → 11.2 Connect your IDE.

3. Mark at least one acceptance criterion as Ready

Acceptance criteria start as draft. On the Track tab, approve at least one AC to move it to Ready — that's what makes it claimable. Run Prepare for Development first so your agent has the full blueprint to work from.

The Development page at a glance

The Development page has three tabs, each with a status dot that turns green as you complete it:

Connection details on the Hand off tab only appear once a Prepare-for-Dev run has completed — there's no point wiring up an agent before it has a blueprint to build from.

Running your first work session

In your IDE, ask your agent something like:

Use the VibeMap MCP server to get the next ready criterion for project <id>, then implement it and submit for review.

Your agent will get the next ready AC, claim it so other sessions don't double up, implement the work in your codebase, and submit for review with a git SHA and diff URL. You watch cards move on the Track tab.

What if I just want the spec as a document?

A few legitimate "just give me the docs" cases:

• Share with a non-developer stakeholder — send them the read-only project summary.
• Import into Linear / Notion / Confluence — pull features, stories, and ACs via the REST API, or export to Jira.
• Back up your spec — the read-only JSON export covered in the developer docs.

↔ The traditional way

Traditionally you'd write a spec document, print or PDF it, and hand-brief a contractor in a kickoff call — then chase status over Slack and reconcile their work against the doc by hand. MCP replaces the document-and-briefing ritual with a live connection: your agent reads the current spec directly and reports each unit of work back onto a board you both watch, so status is never a question you have to ask.

What's next

• Connect your IDE, step by step → 11.2 Connect your IDE
• Watch your agent work → 11.3 Watching progress
• Hit a snag? → 11.4 Troubleshooting