Configuration

The MCP server can be configured using command-line arguments. MCP transport is stdin/stdout (no inbound MCP TCP port).

Command Line Arguments

CLI note: flutter_mcp_cli has a separate --log-level default of error.

v3 Reliability Commands

• Preflight diagnostics:
  • flutter_mcp_cli doctor --json
  • flutter_mcp_cli doctor --json --target ws://127.0.0.1:8181/<token>/ws --timeout-ms 4000
• Safe write controls for snapshot create and bundle create:
  • --check (no writes)
  • --diff (unified diff metadata)
  • --backup (timestamped backup before replace)
  • --no-overwrite (block existing targets)

Error codes and descriptor semantics are documented in Error Code Playbook.

Connection Targeting

Server flags (--dart-vm-host, --dart-vm-port) define defaults, but VM-dependent requests can override connection selection per call.

Resolution Policy

For VM-dependent operations, the server resolves target in this order:

1. Reuse active healthy connection.
2. Reuse sticky target if still discoverable.
3. Auto-attach if exactly one target is discovered.
4. Return connection_selection_required if multiple targets exist and no explicit target is provided.

Per-Request connection Object

VM-dependent tool calls support optional arguments.connection:

{
  "name": "debug_dump_render_tree",
  "arguments": {
    "connection": {
      "targetId": "ws://127.0.0.1:59490/<token>/ws"
    }
  }
}

Supported fields:

• targetId (full VM websocket URI)
• mode: auto, manual, or uri
• host
• port
• uri
• forceReconnect

Zero-Mistake Rules

Use these in order:

1. Safest: set connection.uri to the exact app.debugPort.wsUri value from Flutter machine output.
2. If you use connection.targetId, copy it exactly from discover_debug_apps / availableTargets.
3. Never use plain host:port as targetId (rejected).
4. If you get target_not_found with targetId, retry with connection.uri using exact app.debugPort.wsUri.

Examples:

{
  "name": "get_vm",
  "arguments": {
    "connection": {
      "mode": "manual",
      "host": "localhost",
      "port": 8182
    }
  }
}

{
  "name": "get_vm",
  "arguments": {
    "connection": {
      "mode": "uri",
      "uri": "ws://127.0.0.1:8181/<token>/ws",
      "forceReconnect": true
    }
  }
}

Important:

• Legacy host:port values are rejected for connection.targetId.
• connection.uri is the most robust selector because it preserves tokenized VM paths exactly.
• Full tokenized URI targetId values are accepted. If discovery cannot resolve them, the server attempts direct connect using that URI.
• Tool input schemas are strict: flat aliases like arguments.port, arguments.host, and arguments.uri are rejected.
• connect_debug_app accepts the same connection object.
• Dynamic registry tools (listClientToolsAndResources, runClientTool, runClientResource) also accept optional connection.
• CLI one-shot exec --args, daemon command/execute, and daemon watch/start accept the same nested connection object contract.
• snapshot/create supports per-step args.commands[i].args.connection.
• connect and session_start reject mixed native selector fields and nested connection in the same args object.

Resource URI Targeting

Resource reads can target a specific connection using query params:

• targetId
• mode
• host
• port
• uri
• forceReconnect

Example:

• visual://localhost/view/details?targetId=ws%3A%2F%2F127.0.0.1%3A59490%2F%3Ctoken%3E%2Fws

Flutter Web

Discovery order is:

1. Flutter machine discovery (flutter attach --machine)
2. Port-scan fallback

Manual fallback remains available:

• CLI: --vm-service-uri ws://127.0.0.1:59490/<token>/ws
• MCP calls: arguments.connection.uri