Dusk MCP Setup

The dusk MCP tools ride on the substrate MCP server shipped inside fluttersdk_artisan. Setup is therefore the substrate's .mcp.json plus a one-line provider registration: install the substrate, register DuskArtisanProvider, and the 31 dusk_* tools surface automatically.

Prerequisites

Before wiring any client config:

1. The consumer's pubspec.yaml depends on fluttersdk_artisan and fluttersdk_dusk.
2. The consumer's bin/artisan.dart (the standard scaffold from dart run fluttersdk_artisan install) lists DuskArtisanProvider in its provider factory list, or relies on the auto-discovered lib/app/_plugins.g.dart barrel populated by dart run fluttersdk_artisan plugins:refresh.
3. dart run fluttersdk_artisan list shows the dusk commands (dusk:snap, dusk:tap, etc.). When they are missing, the provider is not registered.

The MCP server stays online with zero apps running. Plugin tool calls lazy-reconnect to the VM Service URI recorded in ~/.artisan/state.json on first call.

Automated install (recommended)

fluttersdk_artisan ships a built-in MCP installer that writes the canonical .mcp.json entry for you. Once dusk is in pubspec.yaml and the provider is registered, the same single command wires Claude Code, Cursor, VS Code, Windsurf, and any other client that reads .mcp.json at the project root:

dart run fluttersdk_artisan mcp:install

The installer is idempotent: pre-existing entries are preserved and the fluttersdk key is replaced in-place on re-run. Override the target path per client:

# VS Code (per-project)
dart run fluttersdk_artisan mcp:install --path .vscode/mcp.json

# Cursor (per-project)
dart run fluttersdk_artisan mcp:install --path .cursor/mcp.json

To remove the entry later:

dart run fluttersdk_artisan mcp:uninstall

Canonical .mcp.json entry

When writing the file by hand (or wiring a client whose path is not yet covered by mcp:install --path):

{
  "mcpServers": {
    "fluttersdk": {
      "command": "dart",
      "args": ["run", "fluttersdk_artisan:mcp"],
      "cwd": "."
    }
  }
}

The cwd field must point at the project root (the directory that contains the consumer's pubspec.yaml). The server binary is the substrate's bin/mcp.dart; the dusk descriptors ride on it.

Per-client install

For Claude Code via CLI:

claude mcp add fluttersdk -- dart run fluttersdk_artisan:mcp
# or project-scoped:
claude mcp add --scope project fluttersdk -- dart run fluttersdk_artisan:mcp

For the VS Code MCP shape (note the "servers" key, not "mcpServers", plus the explicit transport type):

{
  "servers": {
    "fluttersdk": {
      "type": "stdio",
      "command": "dart",
      "args": ["run", "fluttersdk_artisan:mcp"],
      "cwd": "."
    }
  }
}

Reconnect ritual

Claude Code, Continue, and Windsurf do NOT auto-reconnect when .mcp.json or .artisan/mcp.json (the visibility filter) changes. After every edit:

• Claude Code: run /mcp reconnect fluttersdk in the chat. The slash command re-initializes only the named server; other MCP entries stay connected.
• VS Code / Continue: reload the editor window or restart the panel.
• Windsurf: reload the Cascade panel.
• Cursor: picks up changes on its own; no manual action needed.

The substrate MCP server stays online during a reconnect; the client simply re-runs initialize and reads the refreshed tool catalog.

Troubleshooting

The server is online but no app is running. This is normal. The substrate MCP server starts without requiring ~/.artisan/state.json. Every dusk_* tool call returns an actionable error ("VM Service unreachable: state.json missing") until you run dart run fluttersdk_artisan start. Once the state file exists the next tool call lazy-reconnects.

dusk_* tools missing from the catalog. The provider is not registered. Verify by running dart run fluttersdk_artisan list and confirming the dusk:* command block. If the block is empty, add DuskArtisanProvider.new to the consumer's artisanProviders list in bin/artisan.dart, or run dart run fluttersdk_artisan plugins:refresh to regenerate the auto-discovery barrel.

Lazy-reconnect on first tools/call is slow (~1s). Expected; the substrate opens a WebSocket to the VM Service URI on demand. Subsequent calls reuse the cached connection.

Tool visibility filter. Hide a tool surface without uninstalling: edit .artisan/mcp.json to add the tool name under tools.deny. Deny always wins over allow. Run the reconnect ritual after editing.

Related

• overview: tool catalog, dispatch surfaces (ext.dusk.* vs. artisan:dusk:*), lifecycle.
• tool-reference: per-tool input schema and example payloads.
• Substrate MCP setup: the full per-client install matrix for the underlying server.