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:

Selecting your AI client (Claude Code, Cursor, Windsurf, Gemini CLI, or others)
Running the setup command (shown inline, copy-paste ready)
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

npx https://api.app.dev-flow.tech/api/downloads/devflow-mcp-latest.tgz setup

The setup command automatically:

Installs a shell wrapper that resolves the correct node path — this prevents ENOENT errors in GUI apps like Cursor and Windsurf that do not inherit shell PATH
Registers the MCP server with Claude Code
Connects to your DevFlow instance
Opens a browser for authentication on first use

Restart Claude Code after setup.

Cursor

npx https://api.app.dev-flow.tech/api/downloads/devflow-mcp-latest.tgz setup --client cursor

Gemini CLI

npx https://api.app.dev-flow.tech/api/downloads/devflow-mcp-latest.tgz setup --client gemini

Windsurf

npx https://api.app.dev-flow.tech/api/downloads/devflow-mcp-latest.tgz setup --client windsurf

Custom Backend URL

If your DevFlow instance runs on a different URL:

npx https://api.app.dev-flow.tech/api/downloads/devflow-mcp-latest.tgz setup --url https://your-instance.example.com

Updating

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

npx https://api.app.dev-flow.tech/api/downloads/devflow-mcp-latest.tgz 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 details of a specific flow
`flow_create`	Create a new flow
`flow_update`	Update flow state, submit plans, or deliver results
`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

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

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 https://api.app.dev-flow.tech/api/downloads/devflow-mcp-latest.tgz setup to get the latest version
Restart your AI client after updating