DunneFlow · Tutorial

Use DunneFlow from an AI agent

Available15 min· Intermediate· DunneFlow 0.2.0

dunneflow mcp serves your maps to an AI coding agent over the Model Context Protocol (MCP). In this tutorial you register it with an MCP client, check that the agent can see your maps, and ask it questions that it answers from the map rather than by reading files. The example client is Claude Code; any client that launches an MCP server over standard input and output works the same way.

DunneFlow itself calls no model. The agent and its model are yours; DunneFlow only answers the questions put to it.

You'll need#

At least one finished map. The examples assume a source checkout whose maps are under output/, such as the one from Map DunneFlow with DunneFlow.
An MCP client. The example uses Claude Code's claude command.

Steps#

Check the server starts. From the DunneFlow checkout:
```
uv run dunneflow mcp output
```
It waits silently for a client on standard input. Press Ctrl+C to stop it. You do not normally run it by hand; the client launches it.
Register it with your client. With Claude Code, from the DunneFlow checkout:
```
claude mcp add dunneflow -- uv run dunneflow mcp output
```
Everything after -- is the command the client runs. With the application, replace uv run dunneflow with the application's command-line program (see The command line) and output with your maps folder. For other clients, give the same command in their MCP configuration.
Start a session and list the programs. Start your client and ask something like Which programs does DunneFlow have maps for? The agent calls the programs tool and lists the maps under output/.
Open one and read its cover. Ask it to open a program and give you an overview. The agent uses open and then overview, which returns the same content as the dashboard's cover: ways in, what the program touches, and what looks wrong.
Ask about a routine. Ask What does cmd_serve reach, and what would break if I changed _emit? The agent uses touches and impact. Because these come from the map, the answers carry file and line locations you can check.
Let it write its own SQL. Ask a question none of the tools answers directly, such as Which tables are written by more than three routines? The agent can read the graph's schema, offered as a resource, and use the query tool.
Confirm it is read-only. Ask the agent to delete a row through query. It is refused: query accepts reads only, and every map the server opens is read-only at the database connection. No tool can modify an existing map.
Optionally, map a new tree. The analyze tool starts an ordinary dunneflow analyze run in a separate process to write a new map, with the same checks as the Analyse dialog. analysis_status reports on it and analysis_stop ends it.

What you've learned#

How to register dunneflow mcp with an MCP client, using Claude Code as the example.
Which tools an agent gets, and that they call the same code as the dashboard.
That the server cannot change an existing map, and analyze only ever writes a new one.

Next#

Chasing rabbits.
Reference: The MCP server.

Something unclear or out of date? Tell us.

Steps#

Check the server starts. From the DunneFlow checkout:
```
uv run dunneflow mcp output
```
It waits silently for a client on standard input. Press Ctrl+C to stop it. You do not normally run it by hand; the client launches it.
Register it with your client. With Claude Code, from the DunneFlow checkout:
```
claude mcp add dunneflow -- uv run dunneflow mcp output
```
Everything after -- is the command the client runs. With the application, replace uv run dunneflow with the application's command-line program (see The command line) and output with your maps folder. For other clients, give the same command in their MCP configuration.
Start a session and list the programs. Start your client and ask something like Which programs does DunneFlow have maps for? The agent calls the programs tool and lists the maps under output/.
Open one and read its cover. Ask it to open a program and give you an overview. The agent uses open and then overview, which returns the same content as the dashboard's cover: ways in, what the program touches, and what looks wrong.
Ask about a routine. Ask What does cmd_serve reach, and what would break if I changed _emit? The agent uses touches and impact. Because these come from the map, the answers carry file and line locations you can check.
Let it write its own SQL. Ask a question none of the tools answers directly, such as Which tables are written by more than three routines? The agent can read the graph's schema, offered as a resource, and use the query tool.
Confirm it is read-only. Ask the agent to delete a row through query. It is refused: query accepts reads only, and every map the server opens is read-only at the database connection. No tool can modify an existing map.
Optionally, map a new tree. The analyze tool starts an ordinary dunneflow analyze run in a separate process to write a new map, with the same checks as the Analyse dialog. analysis_status reports on it and analysis_stop ends it.