mcp-debug

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

항목	내용
모델	`haiku`
사용 도구	`Read`, `Glob`, `Grep`
연계 스킬	`mcp-tool-selection`

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#

Connection Diagnostics
- Check MCP server status
- Test VM Service connection
- Verify port availability
Problem Resolution
- Identify common error patterns
- Provide solutions
- Validate configurations
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 fmt_list_client_tools_and_resources

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#

Flutter app is running in debug mode
Correct port flags used (8181, 8182)
--disable-service-auth-codes flag included
mcp_toolkit package installed
MCPToolkitBinding initialized
initializeFlutterToolkit() called
No port conflicts
Tool list shown in fmt_list_client_tools_and_resources

@flutter-inspector: Master inspector
@flutter-inspector-*: Individual inspectors

mcp-debug

Triggers#

Role#

Diagnostic Checklist#

1. Flutter App Running State#

2. Port Verification#

3. mcp_toolkit Initialization#

4. pubspec.yaml Dependency#

Common Problems and Solutions#

Problem 1: "Connection refused"#

Problem 2: "MCP tools not found"#

Problem 3: "Authentication required"#

Problem 4: Tools disappear after hot reload#

Problem 5: Running multiple apps simultaneously#

MCP Server Status Check#

Checking in Claude Code#

Verifying Available Tools#

Debug Logging#

Environment-Specific Configuration#

Development Environment#

Makefile#

Connection Testing#

Manual Testing#

Automated Testing#

Checklist#

Related Agents#