🔧 Troubleshooting

1. Connection Issues

   • Ensure your Flutter app is running in debug mode
   • Verify the port matches in both Flutter app and MCP server
   • Check if the port is not being used by another process
   • Run flutter_mcp_cli doctor --json for preflight diagnostics
   • Run flutter_mcp_cli exec --name get_extension_rpcs --args '{}' before app-level inspection
   • Safest selector: use arguments.connection.uri and paste exact Flutter machine app.debugPort.wsUri
   • If you get connection_selection_required, retry with arguments.connection.targetId using one URI from availableTargets (or call connect_debug_app first)
   • Do not use host:port for targetId; use full VM websocket URI or arguments.connection.uri

2. AI Tool Not Detecting Inspector

   • Restart the AI tool after configuration changes
   • Verify the configuration JSON syntax
   • Check the tool's logs for connection errors

3. Dynamic Tools Not Appearing

   • Ensure mcp_toolkit package is properly initialized in your Flutter app
   • Check that tools are registered using MCPToolkitBinding.instance.addEntries()
   • Use listClientToolsAndResources to verify registration
   • Hot reload your Flutter app after adding new tools

4. Missing mcp_toolkit Extensions (Cannot Plug Into App)

   • Symptom: get_extension_rpcs is missing ext.mcp.toolkit.app_errors, ext.mcp.toolkit.view_details, ext.mcp.toolkit.view_screenshots, or ext.mcp.toolkit.inspect_widget_at_point
   • Ensure startup includes MCPToolkitBinding.instance..initialize()..initializeFlutterToolkit();
   • Hot reload may not be enough after instrumentation changes; run hot restart or rerun the app
   • If the app cannot be modified, do not claim screenshot/layout/error inspection works

5. Blank Screenshots

   • Ensure server runs with images enabled (--images)
   • Keep app window visible and foreground; minimized/headless windows can produce blank captures
   • Retry with flutter_mcp_cli exec --name get_screenshots --args '{}'

6. connection_selection_required Errors

   • This means multiple debug targets are available and the server needs an explicit target.
   • Use the returned availableTargets list and retry with connection.targetId.
   • Example: "arguments": {"connection": {"targetId": "ws://127.0.0.1:59490/<token>/ws"}}

7. target_not_found Errors

   • This means the provided connection.targetId was not in current discovery results.
   • Retry with arguments.connection.uri using exact app.debugPort.wsUri from Flutter machine output.

8. First Explicit URI Connect Times Out (connect_failed)

   • Some environments need longer than the default connect timeout for first handshake.
   • Retry the same command once with exact tokenized URI.
   • Verify with flutter_mcp_cli doctor --json --target <ws_uri> --timeout-ms 10000.