AI Agent Troubleshooting

Symptoms:

• get_extension_rpcs does not include:
  • ext.mcp.toolkit.app_errors
  • ext.mcp.toolkit.view_details
  • ext.mcp.toolkit.view_screenshots
  • ext.mcp.toolkit.inspect_widget_at_point
• get_screenshots, get_view_details, or get_app_errors fail even though VM connection works.

Fix:

1. Ensure app dependency: flutter pub add mcp_toolkit
2. Ensure initialization runs before runApp:

MCPToolkitBinding.instance
  ..initialize()
  ..initializeFlutterToolkit();

3. Restart app in debug mode and re-run get_extension_rpcs.
4. Retry runtime tools only after extension RPCs appear.

If the app cannot be modified, state that Flutter MCP cannot attach toolkit extensions to this app and do not claim screenshot/layout/error inspection succeeded.

Cause: multiple debug targets found.

Fix:

1. Read availableTargets from the response.
2. Retry with:

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

Cause: targetId does not match discovered targets for this moment.

Fix:

1. Prefer connection.uri with exact machine app.debugPort.wsUri.
2. Or refresh discover_debug_apps / availableTargets and copy one targetId exactly.
3. Never use plain host:port as targetId.

Example retry:

{
  "arguments": {
    "connection": {
      "uri": "ws://127.0.0.1:59490/<token>/ws"
    }
  }
}

Cause: discovery scans processes named dart/flutter. A desktop app hosts its VM service inside its own native process (my_app, Runner.exe), and an app started with --no-dds has no Dart process at all, so neither shows up.

Fix:

1. Start the app on a known port, for example flutter run -d macos --device-vmservice-port=8765.
2. Pass that port to the server or CLI: --scan-ports=8765 (lists and ranges work too: --scan-ports=8765-8767,9100).
3. Re-run discover_debug_apps; probed ports are verified like any other candidate, so only real Flutter VM services are listed.

Machine discovery (--flutter-project-dir) and an explicit connection.uri remain available when ports are unknown.

• Restart the AI client after MCP config changes.
• Ensure JSON syntax is valid.
• Verify command points to existing compiled binary.
• Confirm Flutter app is running in debug mode.
• Run flutter-mcp-toolkit doctor --json to check environment prerequisites.

• Ensure --images is enabled.
• For clients with limited resource support, use --no-resources and call tool variants.
• For file-based image workflows (for example RooCode), use --save-images.
• Verify toolkit extension ext.mcp.toolkit.view_screenshots is present.

• Ensure --resources is enabled (or call get_view_details tool variant).
• Verify toolkit extension ext.mcp.toolkit.view_details is present.
• If multiple apps are running, pin target with arguments.connection.uri.
• Retry after hot restart if the app was just instrumented.

• Verify toolkit extension ext.mcp.toolkit.inspect_widget_at_point is present.
• Retry with explicit target selection (arguments.connection.targetId or arguments.connection.uri).
• Confirm provided x and y are global logical coordinates.

• Verify MCPToolkitBinding.instance.addEntries(...) is called.
• Hot reload or restart the Flutter app.
• Use fmt_list_client_tools_and_resources to verify registration.