The MCP server.
Thirteen tools, one endpoint.
Vibeflow ships a Model Context Protocol server — two ways in. Start
the local server with vibeflow kanban (or
vibeflow serve in API-only mode) and the MCP
endpoint is live at /api/mcp over the
Streamable HTTP transport; or have your client spawn
vibeflow mcp --project <dir> per
project over stdio — no port, nothing to keep running. Either way,
connect a client and your agent can list, claim and update tasks
directly.
Connect
One endpoint, loopback by default.
The server speaks the MCP Streamable HTTP transport: POST JSON-RPC
to http://localhost:3700/api/mcp, keep the
mcp-session-id the server returns from
initialize, and close the session with
DELETE. Clients are configured against the URL only — see the
MCP documentation
for your client's exact syntax.
The handshake below is enough to prove the endpoint is alive:
a correct initialize answers 200 with
a session id header and serverInfo.name:
"vibeflow".
-
Start first — no server, no endpoint.
vibeflow kanbanis the shortest path. - Loopback only — without a token, non-loopback requests are refused with 401.
- Session lifetime — idle sessions are closed after 30 minutes; a client re-initializes transparently.
stdio
Or spawn one server per project — no port at all.
Don't want a running server? Your MCP client can spawn
vibeflow mcp --project <dir>
itself: one process per project, JSON-RPC on stdin/stdout, the
same thirteen tools. No port, no session lifecycle, nothing to
keep running — and the process exits when the client closes
stdin.
Add the server to your client's MCP config (Claude Desktop,
Cursor, .mcp.json — the shape is the
same everywhere) and the client owns the lifecycle:
-
--projectis required — a spawned client's cwd (often your home directory) is never trusted; the root is resolved and validated once at startup. - stdout is the protocol — the startup announcement and any refusal go to stderr, so every line on stdout is a valid JSON-RPC frame.
- Same thirteen tools — stdio and HTTP mount the identical manifest; only the transport differs.
Why one server per project. The root is resolved once, at startup, and every tool call uses that one root. A server therefore has exactly one project: it cannot write into the wrong one, and there is no path to validate on every call.
Don't point one global server at every repo. A
project argument per call is deliberately
not supported — one process serves one root, resolved at startup.
Configure the server per project, with the project.
Tool reference
Thirteen tools, each mirroring a command.
Every tool wraps the same operation as its CLI equivalent, so the rules your agent learns from the commands carry over unchanged.
| Tool | What it does | CLI equivalent |
|---|---|---|
list_tasks |
List tasks with optional filters — the same listing as `vibeflow tasks` (same filters, same scope, same order). | tasks --status --type --user --tag --search --limit --all --fields --children |
get_task |
Get a single task by ID with full details including comments and files. | tasks --get |
get_project |
Return the resolved project this server is attached to: name, absolute root, git branch and mode. | status |
create_task |
Create a new task with title, description, and metadata. | tasks --add --title --description --type --priority --tag --parent --url --selector --sort-key --fields |
update_task |
Update an existing task. | tasks --edit --set-status --title --description --branch --comment --commit-message --set-verify --verify-reason --set-attention --clear-attention --set-parent --no-parent --relates --blocks --unrelates --unblocks --fields |
claim_next_task |
Claim the highest-priority todo task and set it to in-progress: the returned object IS the claimed task. | tasks --next --type --tag |
add_comment |
Add a comment to a task without changing any of its fields. | tasks --edit --comment |
attach_file |
Attach a file to a task (content as base64) without changing any of its fields. | tasks --edit --set-status --report-file --attach |
get_file |
Download a file attached to a task, returned as base64 with its filename, content type and size. | tasks --get --get-file --out |
pull |
Pull the online board into the local task store: the inverse of a push. | pull --board --out --prefer-remote --prefer-local --dry-run |
verify_task |
Run visual verification on a task with the Playwright engine: it loads the task's annotated page (url + selector) and compares the live element against the baseline captured at annotation time. | verify --json --url --timeout |
start_kanban |
Start the local kanban board server and return the instruction block the CLI prints: the kanban URL, the localhost URL when bound to 0.0.0.0, the agent prompt, and the overlay integration guide. | kanban --port --host |
get_integration_guide |
Get the overlay/bookmarklet integration instructions — the text of the /inject page: the script tag to paste, the browser-console snippet, the bookmarklet, and the /inject URL. | kanban |
Security model
Loopback first, token if you must.
-
No token configured — the endpoint serves loopback (
127.0.0.1/::1) only; every other address gets 401. -
Token configured — requests must carry it as a Bearer token; it is read from
~/.vibeflow/auth.json. -
LAN sharing —
--host 0.0.0.0opens the board to your network, but the MCP endpoint stays closed until a token exists. - stdio transport — no listening socket at all: the pipes belong to the spawning client, so the loopback and token rules above describe the HTTP endpoint only.
- Status — the MCP server is stable and supported. It is pinned to one project root, and every refusal comes back as a code plus a recovery hint.
If something looks wrong
Common questions.
Is the MCP server stable?
Yes — the MCP server is stable. It is pinned to one project root, every refusal comes back as a code plus a recovery hint, and dryRun is a real preview: it answers with what would have happened and writes nothing.
My client gets 401 Unauthorized.
Without a token configured, the endpoint answers loopback only. A request from any other address is refused with MCP requires authentication for non-loopback connections. If you need remote access, configure an auth token in ~/.vibeflow/auth.json and send it as a Bearer token.
Do the tools behave differently from the CLI?
No — the thirteen tools wrap the same operations as the commands they mirror: list_tasks returns roots only (unless you ask for children), claim_next_task never claims a child, and the review transition enforces the same report and verification gates.
Related pages
Where to go next.
- How to use Vibeflow — the three-step CLI workflow
- vibeflow tasks — the commands these tools mirror
- vibeflow kanban — the shortest path to a running endpoint
- vibeflow serve — API-only mode for existing apps
- Give your AI agent UI context — the problem this whole workflow solves
Ten seconds to your
first annotated task.
No account, no cloud, no browser extension.
Apache-2.0 · Node.js 22+ · tasks stay in your repository