Skip to content
MCP/U

Debug Connection Issues

This guide covers the most common connection issues and how to resolve them.

Serial Connection Issues

Section titled “Serial Connection Issues”

”Permission Denied” on Linux

Section titled “”Permission Denied” on Linux”

Symptom: Error: Permission denied /dev/ttyACM0

Cause: Your user isn’t in the dialout group.

  1. Add your user to the dialout group:

    Terminal window
    sudo usermod -aG dialout $USER

  2. Log out and log back in (or reboot)

  3. Verify:

    Terminal window
    groups | grep dialout

Device Not Appearing

Section titled “Device Not Appearing”

Symptom: /dev/ttyUSB* or /dev/ttyACM* doesn’t show your device

Causes and solutions:

CauseSolution
Charge-only USB cableUse a data-capable USB cable
USB port issueTry a different USB port
Board not poweredCheck the board’s power LED
Driver missing (Windows)Install CH340/CP2102 driver

Check if device is detected:

Terminal window
# Before plugging in
ls /dev/tty* > before.txt
# Plug in device
ls /dev/tty* > after.txt
diff before.txt after.txt

Wrong Baud Rate

Section titled “Wrong Baud Rate”

Symptom: Garbled output in Serial Monitor, or client can’t communicate

Solution: Verify the baud rate matches your firmware:

// Default is 115200
mcp.begin(Serial, 115200);

In client config:

"env": {
  "SERIAL_PORT": "/dev/ttyACM0",
  "SERIAL_BAUD": "115200"
}

Port Already In Use

Section titled “Port Already In Use”

Symptom: Error: Port is in use or Resource busy

Check what’s using the port:

Terminal window
# Linux
lsof /dev/ttyACM0


# macOS
lsof /dev/cu.usbserial-*

Common culprits:

  • Arduino IDE Serial Monitor
  • PlatformIO Device Monitor
  • Another terminal with serial open

Solution: Close all other serial connections and try again.

WiFi TCP Connection Issues

Section titled “WiFi TCP Connection Issues”

Connection Refused

Section titled “Connection Refused”

Symptom: Error: connect ECONNREFUSED or Connection refused

Causes and solutions:

CauseSolution
Wrong IP addressCheck Serial Monitor for correct IP
ESP32 not running serverVerify “TCP server listening on port 3000” in Serial Monitor
Wrong portDefault is 3000, check your firmware
Firewall blockingTemporarily disable firewall or add exception

Verify ESP32 is listening:

Terminal window
# Check if port is open
nc -z 192.168.1.42 3000

Can’t Find ESP32 IP

Section titled “Can’t Find ESP32 IP”

Symptom: Don’t know the ESP32’s IP address

Solution: Open Serial Monitor after boot — the ESP32 prints:

Connecting to WiFi.....
IP: 192.168.1.42
TCP server listening on port 3000

Not on Same Network

Section titled “Not on Same Network”

Symptom: Connection times out

Solution: Ensure your computer and ESP32 are on the same local network (same WiFi router). Corporate networks may isolate devices.

Firewall Blocking

Section titled “Firewall Blocking”

Symptom: Connection works from another device but not your computer

Solution:

  • Linux: sudo ufw allow 3000/tcp
  • macOS: System Settings → Network → Firewall → Allow incoming connections
  • Windows: Windows Defender Firewall → Allow an app through firewall

ESP32-Specific Issues

Section titled “ESP32-Specific Issues”

Not Responding After Flash

Section titled “Not Responding After Flash”

Symptom: ESP32 doesn’t respond to commands after uploading new firmware

Cause: Some ESP32 boards reset when the USB connection is opened (DTR), which can interfere with the first connection.

Solution: Wait before connecting:

Terminal window
# Wait 2 seconds after flash
sleep 2 && npx mcpu-client

Or in your agent config, add a startup delay.

Tool Not Found

Section titled “Tool Not Found”

Symptom: Method not found or tool doesn’t appear in list

Causes:

CauseSolution
Tool not registeredAdd mcp.add_tool() in setup() before mcp.begin()
Client not restartedRestart the client after flashing new firmware
Wrong device IDVerify device ID matches in DEVICES config

Debug with MCP Inspector:

Terminal window
SERIAL_PORT=/dev/ttyACM0 npx @modelcontextprotocol/inspector npx mcpu-client

Open the browser URL and call list_tools to see what the firmware actually exposes.

Using MCP Inspector for Debugging

Section titled “Using MCP Inspector for Debugging”

MCP Inspector is the best tool for debugging MCP/U connections:

Terminal window
# Serial
SERIAL_PORT=/dev/ttyACM0 npx @modelcontextprotocol/inspector npx mcpu-client


# TCP
DEVICES=mydevice:192.168.1.42:3000:tcp npx @modelcontextprotocol/inspector npx mcpu-client

What to check in Inspector

Section titled “What to check in Inspector”
  1. Call get_info — verifies device is responding
  2. Call list_tools — shows all available tools
  3. Call a simple tool like gpio_read — tests basic functionality
  4. Check for errors — look at the response JSON for error fields

Quick Diagnostic Checklist

Section titled “Quick Diagnostic Checklist”
  • Device is powered (check LED)
  • Correct serial port / IP address
  • Correct baud rate (115200 default)
  • No other app using the port
  • Linux: user in dialout group
  • TCP: same network as ESP32
  • Client restarted after firmware flash
  • Device ID matches in DEVICES config

Next Steps

Section titled “Next Steps”