# Configuration

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

## Command Line Arguments

| Option | Description |
| --- | --- |
| `--dart-vm-host` | The host for the Dart VM connection. Defaults to `localhost`. |
| `--dart-vm-port` | The port for the Dart VM connection. Defaults to `8181`. |
| `--resources` | Enable or disable support for resources (widget tree, screenshots). Defaults to `true`. |
| `--images` | Enable or disable support for images (screenshots). Defaults to `true`. |
| `--dumps` | Enable or disable support for debug dump operations (e.g., `dump_render_tree`). Defaults to `false`. |
| `--dynamics` | Enable or disable support for dynamic tool registration. Defaults to `true`. |
| `--await-dnd` | Await until a dynamic tool registration connection is established. This can be useful for some AI clients. Defaults to `false`. |
| `--save-images` | Save captured images as files instead of returning them as base64 data. Defaults to `false`. |
| `--flutter-project-dir` | Optional Flutter project directory used by machine discovery (`flutter attach --machine`). |
| `--flutter-device` | Optional Flutter device for machine discovery (for example `chrome`). |
| `--flutter-discovery-timeout-ms` | Timeout in milliseconds for machine discovery. Defaults to `2500`. |
| `--scan-ports` | Extra ports probed during discovery, as a comma-separated list of ports and ranges (for example `8765-8767,9100`). Needed for a desktop app, whose VM service listens inside the application process, and for any app started with `--no-dds`. |
| `--prefer-target-label` | Prefer the discovered target whose label contains this text, so auto-attach can pick between several running apps. Labels come from the app itself (`MCPToolkitBinding.setAppIdentity`). Matching narrows the candidates only at the auto-attach step, so an active connection and a target connected to explicitly still win; a value that matches no target is ignored. |
| `--log-level` | The logging level for the server. Can be `debug`, `info`, `notice`, `warning`, `error`, `critical`, `alert`, or `emergency`. Defaults to `critical`. Log levels are based on https://spec.modelcontextprotocol.io/specification/2025-03-26/server/utilities/logging/#log-levels |
| `--environment` | The environment mode. Can be `development` or `production`. Defaults to `production`. |
| `-h`, `--help` | Show the usage text. |

CLI note: `flutter-mcp-toolkit` has a separate `--log-level` default of `error`.

## v3 Reliability Commands

- Preflight diagnostics:
  - `flutter-mcp-toolkit doctor --json`
  - `flutter-mcp-toolkit 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, descriptors, and recovery are documented in [AI troubleshooting](/ai_agents/troubleshooting).


## 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 use optional `arguments.connection`. On **MCP**
`tools/call`, the tool **`name`** must use the v3 **`fmt_`** prefix (e.g.
`fmt_get_vm`). The **CLI** still uses bare catalog names:
`flutter-mcp-toolkit exec --name get_vm --args '...'`.

```json
{
  "name": "fmt_get_vm",
  "arguments": {
    "connection": {
      "mode": "manual",
      "host": "localhost",
      "port": 8182
    }
  }
}
```

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

Supported `connection` fields:

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

### Zero-Mistake Rules

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`.

v2 → v3 migration (MCP tool names, binaries, `mcpServers` keys): [Migrating from v2.x to v3.0](/start_here/migration_v2_to_v3).

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` (MCP: **`fmt_connect_debug_app`**) accepts the same `connection` object.
- Dynamic registry tools (`fmt_list_client_tools_and_resources`, `fmt_client_tool`, `fmt_client_resource`) 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`