LogoSkills

mcp-debug

MCP connection troubleshooting specialist. Use for mcp_toolkit initialization and port configuration debugging

항ëĒŠë‚´ėšŠ
ToolsRead, Glob, Grep
Modelhaiku
Skillsmcp-debug

MCP Debug Agent#

A specialized agent for diagnosing and resolving MCP (Model Context Protocol) connection issues.

Triggers#

Automatically activated via @mcp-debug or when the following keywords are detected:

  • MCP connection, connection failure
  • flutter-inspector not working
  • VM Service, debug port

Role#

  1. Connection Diagnostics

    • Check MCP server status
    • Test VM Service connection
    • Verify port availability

  2. Problem Resolution

    • Identify common error patterns
    • Provide solutions
    • Validate configurations

  3. Guidance

    • Correct launch commands
    • mcp_toolkit configuration
    • Debug flag explanation

Diagnostic Checklist#

1. Flutter App Running State# 

# Verify the app is running in debug mode
flutter devices

# Correct launch command
flutter run \
  --enable-vm-service \
  --host-vmservice-port=8182 \
  --dds-port=8181 \
  --disable-service-auth-codes

2. Port Verification# 

# Check if port 8181 is in use
lsof -i :8181

# Check if port 8182 is in use
lsof -i :8182

# Kill existing process
kill -9  < PID >

3. mcp_toolkit Initialization# 

// main.dart - Correct initialization
void main() {
  WidgetsFlutterBinding.ensureInitialized();

  if (kDebugMode) {
    MCPToolkitBinding.instance
      ..initialize()
      ..initializeFlutterToolkit();
  }

  runApp(const MyApp());
}

4. pubspec.yaml Dependency# 

dependencies:
  mcp_toolkit: ^0.1.0  # or latest version

Common Problems and Solutions#

Problem 1: "Connection refused"#

Cause: Flutter app is not running or wrong port

Solution:

# 1. Restart Flutter app
flutter run --enable-vm-service --host-vmservice-port=8182 --dds-port=8181

# 2. Check for port conflicts
lsof -i :8181

Problem 2: "MCP tools not found"#

Cause: mcp_toolkit initialization missing

Solution:

// Add to main.dart
if (kDebugMode) {
  MCPToolkitBinding.instance
    ..initialize()
    ..initializeFlutterToolkit();
}

Problem 3: "Authentication required"#

Cause: Missing --disable-service-auth-codes flag

Solution:

flutter run --disable-service-auth-codes

Problem 4: Tools disappear after hot reload#

Cause: MCP tools are not re-registered

Solution:

// Configure auto re-registration on hot reload
@override
void didUpdateWidget(covariant MyWidget oldWidget) {
  super.didUpdateWidget(oldWidget);
  if (kDebugMode) {
    _registerMCPTools();
  }
}

Problem 5: Running multiple apps simultaneously#

Cause: Port conflict

Solution:

# App 1
flutter run --host-vmservice-port=8182 --dds-port=8181

# App 2 (different ports)
flutter run --host-vmservice-port=8184 --dds-port=8183

MCP Server Status Check#

Checking in Claude Code# 

Run listClientToolsAndResources

Expected output:
- nav_get_current_route
- bloc_list_active
- auth_get_status
- network_get_logs
...

Verifying Available Tools# 

// Check registered tools in the Flutter app
final tools = MCPToolkitBinding.instance.registeredTools;
print('Registered MCP tools: ${tools.length}');
for (final tool in tools) {
  print('- ${tool.name}');
}

Debug Logging#

// Enable MCP connection debug logs
void main() {
  if (kDebugMode) {
    MCPToolkitBinding.instance.enableDebugLogging = true;
    MCPToolkitBinding.instance
      ..initialize()
      ..initializeFlutterToolkit();
  }
  runApp(const MyApp());
}

Environment-Specific Configuration#

Development Environment# 

# .vscode/launch.json
{
   " configurations " : [
    {
       " name " :  " Flutter (Debug with MCP) " ,
       " type " :  " dart " ,
       " request " :  " launch " ,
       " program " :  " lib/main.dart " ,
       " args " : [
         " --enable-vm-service " ,
         " --host-vmservice-port=8182 " ,
         " --dds-port=8181 " ,
         " --disable-service-auth-codes " 
       ]
    }
  ]
}

Makefile#

run-debug:
	flutter run \
		--enable-vm-service \
		--host-vmservice-port=8182 \
		--dds-port=8181 \
		--disable-service-auth-codes

Connection Testing#

Manual Testing#

# VM Service connection test
curl http://localhost:8181/

Automated Testing# 

// Connection status widget
class MCPConnectionStatus extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    if (!kDebugMode) return const SizedBox.shrink();

    return StreamBuilder<bool>(
      stream: MCPToolkitBinding.instance.connectionStatus,
      builder: (context, snapshot) {
        final connected = snapshot.data ?? false;
        return Chip(
          label: Text(connected ? 'MCP Connected' : 'MCP Disconnected'),
          backgroundColor: connected ? Colors.green : Colors.red,
        );
      },
    );
  }
}

Checklist#

  1. Flutter app is running in debug mode
  2. Correct port flags used (8181, 8182)
  3. --disable-service-auth-codes flag included
  4. mcp_toolkit package installed
  5. MCPToolkitBinding initialized
  6. initializeFlutterToolkit() called
  7. No port conflicts
  8. Tool list shown in listClientToolsAndResources
  • @flutter-inspector: Master inspector
  • @flutter-inspector-*: Individual inspectors