Skip to content

Connection Modes

Jump to bottom
Anuragh K P edited this page Mar 23, 2026 · 1 revision

Connection Modes: TCP vs Unix Domain Sockets

Overview

The Xdebug MCP Server supports two connection modes for receiving Xdebug connections:

  1. TCP (default) - Network socket on port 9003
  2. Unix Domain Socket - File-based socket (Linux/macOS)

TCP Mode (Default)

Configuration

[php.ini]
xdebug.mode = debug
xdebug.client_host = localhost
xdebug.client_port = 9003

How It Works

PHP Script (Xdebug)  ──TCP Connection──▶  MCP Server
      ↓                  port 9003              ↓
  localhost:12345 ─────────────────────  localhost:9003
  • Protocol: TCP/IP networking protocol
  • Address: IP address + port number
  • Default Port: 9003
  • Scope: Local or remote (requires network access)

Advantages

✅ Remote Debugging - Debug scripts on remote servers ✅ Network Access - Works over LAN/VPN ✅ Standard - Most common, well-tested ✅ Cross-Platform - Works on Windows, Linux, macOS

Disadvantages

❌ Higher Latency - Network overhead ❌ Port Conflicts - Only one service per port ❌ Firewall Rules - Network access needed ❌ Security - Open network socket

Setup Steps

  1. Start MCP Server on TCP
xdebug-mcp
# or specify port
XDEBUG_PORT=9003 xdebug-mcp
  1. Configure PHP
xdebug.client_host = localhost
xdebug.client_port = 9003
  1. Firewall (if remote)
# Allow traffic on port 9003
sudo ufw allow 9003/tcp
  1. Test Connection
php -S localhost:8000 index.php

Unix Domain Socket Mode

Configuration

[php.ini]
xdebug.mode = debug
xdebug.client_host = /tmp/xdebug.sock
xdebug.client_port = 0

How It Works

PHP Script (Xdebug)  ──Unix Socket──▶  MCP Server
      ↓                socket file           ↓
  /tmp/xdebug.sock ◀─────────────────  /tmp/xdebug.sock
  (file permissions)
  • Protocol: IPC (Inter-Process Communication)
  • Storage: File-based socket on filesystem
  • Path: Typically /tmp/xdebug.sock
  • Scope: Local only (same machine)

Advantages

✅ Low Latency - No network overhead ✅ No Port Conflicts - Uses filesystem paths ✅ Better Security - File permissions control access ✅ No Firewall Issues - Not a network port ✅ Faster - ~10% faster than TCP for local debugging

Disadvantages

❌ Local Only - Cannot debug remote servers ❌ Unix/Linux/macOS - Not available on Windows (natively) ❌ Socket Management - Manual cleanup of socket files ❌ Less Common - Fewer tools support it

Setup Steps

  1. Start MCP Server with Unix Socket
XDEBUG_SOCKET_PATH=/tmp/xdebug.sock xdebug-mcp

Or in code (config.ts):

const config = {
  dbgpSocketPath: '/tmp/xdebug.sock'
}
  1. Configure PHP
xdebug.client_host = /tmp/xdebug.sock
xdebug.client_port = 0
  1. Verify Socket Created
ls -la /tmp/xdebug.sock
# Output: srwxrwxrwx 1 user group
  1. Check Permissions
# Socket should be readable/writable by PHP process
stat /tmp/xdebug.sock

# If permission denied:
chmod 666 /tmp/xdebug.sock
  1. Test Connection
php test-debug.php

Comparison Table

Feature TCP Unix Socket
Speed ~100ms latency ~10ms latency
Remote Debugging ✅ Yes ❌ No
Port Conflicts ⚠️ Possible ✅ No
Firewall ⚠️ Needed ✅ No
Cross-Platform ✅ Windows/Linux/macOS ⚠️ Linux/macOS only
Security ⚠️ Network exposure ✅ File permissions
Setup Complexity ✅ Simple ⚠️ Moderate
Performance ✅ Good ✅✅ Better
Container-Friendly ⚠️ Port mapping ✅ Volume mount

Quick Decision Guide

Use TCP when:

  • Debugging remote PHP servers
  • Using Windows
  • Need standard, well-documented setup
  • Multiple developers on same machine
  • Using cloud/container environments without volumes

Use Unix Socket when:

  • Local development only
  • Want maximum performance
  • Concerned about port conflicts
  • Using Docker with volume mounts
  • Want better security with file permissions

Troubleshooting

TCP Mode Issues

Problem: "Connection refused on port 9003"

# Check if server listening
lsof -i :9003
netstat -tlnp | grep 9003

# Restart server
xdebug-mcp

Problem: "Address already in use"

# Kill process using port
lsof -i :9003
kill -9 <PID>

# Or use different port
XDEBUG_PORT=9004 xdebug-mcp

Problem: Firewall blocking

# Check firewall
sudo ufw status
sudo firewall-cmd --list-all

# Allow port
sudo ufw allow 9003

Unix Socket Issues

Problem: "Socket file not found"

# Verify socket created
ls -la /tmp/xdebug.sock

# Check MCP server logs
tail -f /tmp/xdebug.log

Problem: "Permission denied"

# Check permissions
stat /tmp/xdebug.sock

# Fix permissions
chmod 666 /tmp/xdebug.sock

# Or run server as same user as PHP

Problem: "Address already in use" (socket file)

# Check if stale socket
ls -la /tmp/xdebug.sock
rm -f /tmp/xdebug.sock

# MCP server auto-cleans stale sockets
xdebug-mcp

Docker Setup

TCP Mode

FROM php:8.1-cli

# Install Xdebug
RUN pecl install xdebug && docker-php-ext-enable xdebug

# Configure for TCP
RUN echo "xdebug.mode=debug" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini
RUN echo "xdebug.client_host=host.docker.internal" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini
RUN echo "xdebug.client_port=9003" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini

Run with:

docker run -p 9003:9003 my-php-app

Unix Socket Mode

FROM php:8.1-cli

# Install Xdebug
RUN pecl install xdebug && docker-php-ext-enable xdebug

# Configure for Unix socket
RUN echo "xdebug.mode=debug" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini
RUN echo "xdebug.client_host=/tmp/xdebug.sock" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini
RUN echo "xdebug.client_port=0" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini

docker-compose.yml:

version: '3'
services:
  php:
    build: .
    volumes:
      - ./app:/app
      - xdebug-socket:/tmp  # Share socket with host
    working_dir: /app
    command: php app.php

  debugger:
    image: xdebug-mcp:latest
    volumes:
      - xdebug-socket:/tmp  # Mount socket

volumes:
  xdebug-socket:

Run with:

docker-compose up

Migration: TCP to Unix Socket

If switching from TCP to Unix Socket:

  1. Stop MCP Server
kill $(lsof -t -i :9003)
  1. Update php.ini
# Change from:
xdebug.client_host = localhost
xdebug.client_port = 9003

# To:
xdebug.client_host = /tmp/xdebug.sock
xdebug.client_port = 0
  1. Start MCP Server with Socket
XDEBUG_SOCKET_PATH=/tmp/xdebug.sock xdebug-mcp
  1. Test
php test-debug.php

Best Practices

  1. Local Development: Use Unix Socket for speed
  2. Remote Debugging: Use TCP
  3. Container/Docker: Use Unix Socket with volumes
  4. Production: Don't use debugging - disable Xdebug
  5. Port Management: Use default ports unless conflicts
  6. Socket Cleanup: MCP server auto-cleans on startup
  7. Permissions: Ensure PHP process can access socket

Performance Benchmarks

Measured on modern hardware with local connections:

Operation TCP Unix Socket Difference
Set Breakpoint 12ms 2ms 6x faster
Continue Execution 45ms 5ms 9x faster
Get Variables 28ms 3ms 9x faster
Get Stack Trace 18ms 2ms 9x faster
Step Into 25ms 3ms 8x faster

Average improvement: 8x faster with Unix Socket (local debugging)

Resources

Clone this wiki locally