MCP Setup
Make the crumbs_* tools appear in Claude Code, Cursor or any other MCP client: install crumbs, write the dowel entry in .mcp.json, reconnect, and optionally filter the tools.
On this page
Quick Reference#
| Step | Command |
|---|---|
| 1. Install | flutter pub add crumbs, then dart run crumbs crumbs:install |
| 2. Write the entry | dart run crumbs mcp:install |
| 3. Reconnect | /mcp reconnect dowel in Claude Code |
| 4. Start the app | ./bin/dowel start --device=chrome, or the dowel_start tool |
| 5. Verify | Call crumbs_tail with {"limit": 5} |
Install crumbs#
flutter pub add crumbs
dart run crumbs crumbs:install
crumbs goes under dependencies, not dev_dependencies, because lib/main.dart imports it. The installer scaffolds the dowel harness, registers CrumbsDowelProvider through lib/app/_plugins.g.dart and installs crumbs in lib/main.dart; see Installation for the manual route.
Write the MCP entry#
The crumbs_* tools ride on the dowel MCP server, so there is no separate crumbs entry: the server key is dowel.
dart run crumbs mcp:install
The command writes the dowel entry into .mcp.json at the project root, keeps any other entry, and replaces its own on a rerun:
| Scaffold state | Entry |
|---|---|
./bin/dowel exists, POSIX host |
./bin/dowel mcp:serve |
No ./bin/dowel, or a Windows host |
dart run crumbs mcp:serve |
{
"mcpServers": {
"dowel": {
"command": "./bin/dowel",
"args": ["mcp:serve"],
"cwd": "."
}
}
}
cwd must resolve to the project root, the directory with pubspec.yaml and bin/dispatcher.dart.
Clients#
A client reads its server list at startup and does not reload a changed entry on its own.
| Client | Install or reload |
|---|---|
| Claude Code | Reads .mcp.json from the project, or claude mcp add dowel -- ./bin/dowel mcp:serve; run /mcp reconnect dowel after a change |
| Cursor | .cursor/mcp.json (project) or ~/.cursor/mcp.json (user); reload the MCP panel |
| Windsurf | ~/.codeium/windsurf/mcp_config.json; reload the MCP panel |
| Claude Desktop | claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\); quit and relaunch |
Start the app and verify#
./bin/dowel start # chrome, the default device
./bin/dowel start --device=macos # a desktop build
Then ask the agent for a small read:
crumbs_tail {"limit": 5}
A working setup answers {"messages": [...], "cursor": ...}; an empty messages list means the app runs but has logged nothing yet. An error that says no session is recorded means the app was not started through dowel; one that names a missing ext.crumbs.* method means CrumbsPlugin.install() did not run in this build. Restart the app with ./bin/dowel restart when the session is stale.
Filter crumbs tools#
To hide some crumbs tools from the agent, add deny rules to .dowel/mcp.json in the project root:
{
"packages": {
"allow": null,
"deny": []
},
"tools": {
"allow": null,
"deny": ["crumbs_dumps", "crumbs_gates"]
}
}
To serve only the crumbs tools, hiding the substrate and every other plugin:
{
"packages": {
"allow": ["crumbs"],
"deny": []
},
"tools": {
"allow": null,
"deny": []
}
}
Reconnect the client after editing the file. The dowel filter reference covers the environment variables, the CLI flags and how the three layers combine.
Related Documentation#
- MCP overview: how the tools reach the running app.
- Tool reference: every tool's input schema and output shape.
- Installation: the installer and the manual wiring.
- dowel MCP setup: the client matrix of the substrate.