Vibeflow
Start free

The MCP server.
Eleven 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 kanban is 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.
initialize a session
curl -s http://localhost:3700/api/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize",
      "params":{"protocolVersion":"2025-06-18",
      "capabilities":{},"clientInfo":{"name":"curl"}}}'

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 eleven 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:

  • --project is 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 eleven tools — stdio and HTTP mount the identical manifest; only the transport differs.
client config (.mcp.json)
{
  "mcpServers": {
    "vibeflow": {
      "command": "npx",
      "args": ["-y", "@vibeflow-tools/cli", "mcp", "--project", "/path/to/project"]
    }
  }
}

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

Eleven 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.

Vibeflow MCP tools
Tool What it does CLI equivalent
list_tasks List tasks with filters. Roots only unless children is set; the response reports hidden children. tasks + filters
get_task Full details of one task, including comments and files. tasks --get
get_project Report the project this server is attached to: name, absolute root, git branch and mode. Read-only, takes no input. status
create_task Create a task with title, description, type, priority, tags or parent. tasks --add
update_task Edit fields, status, links and the verification verdict (pass, fail or cleared). tasks --edit
claim_next_task Claim the highest-priority root task in todo — never a child. tasks --next
add_comment Add a comment to a task. tasks --comment
attach_file Attach a file to a task (content as base64), e.g. a research report. tasks --report-file
export_prompt Export task(s) as a formatted prompt for LLM consumption. tasks --get --json
verify_task Run visual verification against the task's baseline snapshot. verify
push_tasks Push local tasks to a Vibeflow SaaS workspace. push

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.0 opens 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 eleven 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

Ten seconds to your
first annotated task.

No account, no cloud, no browser extension.

Get started free Star it on GitHub

Apache-2.0 · Node.js 22+ · tasks stay in your repository