MCP Setup

This guide walks you through connecting your AI coding assistant to DevFlow using the Model Context Protocol (MCP).

What is MCP?

The Model Context Protocol (MCP) is a standard for integrating AI assistants with external tools. Instead of copy-pasting context back and forth, MCP gives the AI agent direct access to structured tools — reading flows, creating tasks, updating progress, and more.

Think of it as giving the AI agent a seat at your desk. It can see your project, understand your tasks, and report its work — all through a well-defined interface.

Installing the MCP Server

The DevFlow MCP server works with any MCP-compatible AI client. The recommended way is to use the Setup Wizard in DevFlow, or run the setup command directly.

Setup Wizard (recommended)

Go to Settings > Agent in the DevFlow UI and click Add Client. The interactive wizard walks you through:

1. Selecting your AI client (Claude Code, Cursor, Windsurf, Gemini CLI, or others)
2. Running the setup command (shown inline, copy-paste ready)
3. Confirming the connection is working

The wizard also shows the Client Dashboard — a matrix view of which clients are connected to which projects. This lets you see at a glance where the MCP server is active and manage connections from one place.

Claude Code

Install as a Claude Code plugin:

/plugin marketplace add anthropics/claude-plugins-community
/plugin install devflow

This installs everything in one shot: the MCP server is auto-registered through the plugin’s mcpServers manifest, alongside enforcement hooks, state-specific skills, and slash commands (/devflow-start, /devflow-status, /devflow-next, /devflow-tasks, /devflow-create, /devflow-list, /devflow-review). On first use, a browser opens for authentication.

DevFlow is listed in the official Anthropic community marketplace. No separate npx ... setup step is needed — the plugin handles MCP registration itself (since devflow-mcp 4.23).

Updates: /plugin update devflow. Restart Claude Code after install.

Cursor

npx github:KlausFreiberufler/devflow-mcp setup --client cursor

Gemini CLI

npx github:KlausFreiberufler/devflow-mcp setup --client gemini

Windsurf

npx github:KlausFreiberufler/devflow-mcp setup --client windsurf

Custom Backend URL

If your DevFlow instance runs on a different URL:

npx github:KlausFreiberufler/devflow-mcp setup --url https://your-instance.example.com

Updating

To update to the latest version, run the setup command again:

npx github:KlausFreiberufler/devflow-mcp setup

The setup detects existing registrations and updates them.

Authentication

The MCP server uses your DevFlow credentials. On first use, a browser window opens for login. Your session is stored locally so you do not need to re-authenticate every time.

Alternatively, you can use an API Token (create one under Settings > Agent):

export DEVFLOW_TOKEN="your-token"

The agent inherits your permissions — it can only access projects and flows that you have access to.

Project Linking

Project linking happens automatically. When the agent calls devflow_init with a flow ID, DevFlow resolves the project from the flow and scopes the session accordingly. No manual configuration or .devflow.json file is needed.

If you work across multiple repositories, each repository directory is detected independently. The agent always operates in the context of the flow it was initialized with.

Available Tools

Once connected, the AI agent has access to the following tools:

Tool	Purpose
devflow_init	Start a work session on a flow (required first)
flow_list	List all flows in a project
flow_get	Get full flow context — description, plan, attachments (markdown inline + images as content blocks)
flow_create	Create a new flow
flow_update	Update flow state, submit plans, or deliver results
flow_upload	Upload a file (markdown, HTML, PDF, image, etc.) as an attachment — use kind: "plan" to link it as the flow’s implementation plan
flow_get_feedback	Check for user feedback on plans or reviews
task_list	List tasks for a flow
task_create	Create tasks to break down work
task_update	Mark tasks as complete or update details
project_knowledge_get	Read the project knowledge base
project_knowledge_update	Update project knowledge
project_guidelines_get	Read project guidelines
release_list	List releases
release_get	Get release details
release_create	Create a new release
release_update	Update a release
search	Search across flows, tasks, and projects
agent_session_create	Start an agent work session
agent_session_log	Log progress during a session
agent_session_complete	Complete an agent session
wiki_search, wiki_get_page, wiki_list_by_type, wiki_backlinks, wiki_graph_neighbors, wiki_get_flow_context, wiki_get_project_context	Knowledge wiki reads (DF-226)
adr_list, adr_get, adr_accept, adr_update_status, adr_get_audit_log	Architecture Decision Records (DF-225/241/248)
knowledge_backfill_request, knowledge_draft_list, knowledge_draft_create, knowledge_draft_accept, knowledge_draft_reject, knowledge_harvest, knowledge_check_flow, knowledge_check_drift	MCP-first knowledge drafts + harvest (DF-244/245/246/238)

Note on enforcement (DF-248): Tool availability depends on flow state. Read tools (wiki_*, adr_list/get, search, knowledge_check_*) are allowed in every working state. Write tools (knowledge_draft_*, adr_accept, flow_upload, …) are allowed in planning and in_progress. knowledge_harvest remains callable in done so the post-flow harvest hint works. Details in CLAUDE.md → “MCP Enforcement Allowlist”.

The agent uses these tools to participate in the full flow lifecycle — from planning through implementation to review.

Rich Attachments & Plans as Markdown Files

As of DevFlow 4.3, the MCP server treats attachments as first-class context:

• flow_get loads full content. Markdown, plain text, HTML and JSON attachments are embedded inline in the tool response under ## Attachment: <filename> — the agent sees the full file content, not just a link. Images (both attachments and images embedded in the flow description via the rich-text editor) are returned as MCP image content blocks, so the agent can actually see them.
• flow_upload supports a kind parameter. Use kind: "plan" to upload the implementation plan as a markdown file — DevFlow automatically links it to the flow, so it renders as formatted markdown in the UI (and the implementation_plan database field becomes a pointer, not a blob). Other allowed values: summary, design, notes.
• Auth-protected content. All attachment content is served through GET /api/flows/:id/attachments/:attId/content, which requires authentication and flow access. The legacy public /uploads/flow-attachments/* URLs are blocked. In the UI, HTML and PDF attachments render inline in the browser (via blob URLs) — no download required.

This gives agents the full picture of a flow (plans, design docs, screenshots, reference HTML) without having to guess or ask.

Pipeline Integration

Projects with pipeline rules configured get enhanced agent behavior:

• Step-aware permissions — The agent only gets tools appropriate for the current pipeline step
• Gate enforcement — Steps with transitionPolicy: human_only block the agent until a human approves in the UI
• Skill assignment — Each step can have skills assigned that guide the agent’s behavior
• Retry handling — If the human rejects work, the agent gets the feedback and can retry

The backend is the sole source of truth for what the agent is allowed to do. The MCP server simply relays these permissions without adding its own logic.

Testing the Connection

After setup, verify the connection works by asking your AI assistant to list your flows:

“List my DevFlow flows”

The agent should call flow_list and return your active flows. If you see your project data, the connection is working.

You can also check the Client Dashboard in Settings > Agent to confirm the client appears as connected.

Troubleshooting

ENOENT error when starting the MCP server

• This happens when a GUI app (Cursor, Windsurf, VS Code) cannot find node because it does not inherit your shell’s PATH
• Re-run the setup command — it installs a shell wrapper that resolves the node path automatically
• After re-running setup, restart your AI client

Connection timeouts

• Check that your DevFlow backend is reachable: open https://api.app.dev-flow.tech/health in a browser
• If you are behind a VPN or firewall, make sure the MCP server can reach the backend URL
• Verify the URL in your MCP client config matches your DevFlow instance

The agent cannot find any flows

• Verify the MCP server is registered (e.g., claude mcp list for Claude Code)
• Check that you are authenticated
• Make sure you have at least one project with flows

The agent cannot update flows

• Ensure the flow is not locked by another agent session
• Check that the flow is in a state that allows the requested action
• Verify the pipeline transitionPolicy allows agent transitions for the current step

The agent is blocked at a step

• The step may have transitionPolicy: human_only — approve or reject in the DevFlow UI
• Check the pipeline rules in Project Settings > Rules

Update issues

• Run npx github:KlausFreiberufler/devflow-mcp setup to get the latest version
• Restart your AI client after updating