# debug-mcp

> Debug MCP Engine sessions, workers, and gRPC communication issues. Use when troubleshooting MCP server lifecycle, worker registration, etcd coordination, or gRPC connectivity problems.

- Author: Jason
- Repository: jrmatherly/metorial-platform
- Version: 20260121121539
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/jrmatherly/metorial-platform
- Web: https://mule.run/skillshub/@@jrmatherly/metorial-platform~debug-mcp:20260121121539

---

---
name: debug-mcp
description: >
  Debug MCP Engine sessions, workers, and gRPC communication issues.
  Use when troubleshooting MCP server lifecycle, worker registration,
  etcd coordination, or gRPC connectivity problems.
---

# MCP Engine Debugging

Systematic approach to debugging MCP Engine issues including sessions, workers, and gRPC communication.

## Overview

The MCP Engine consists of:

- **Manager**: Coordinates sessions and worker assignment (port 50050)
- **Worker Launcher**: Spawns workers on demand (port 50052)
- **Worker MCP Runner**: Runs MCP servers locally (port 50051)
- **Worker MCP Remote**: Connects to remote MCP servers (port 50053)
- **etcd**: Service coordination and discovery

## Usage

```
/debug-mcp [issue-type]
```

Issue types:

- `session` - Session lifecycle issues
- `worker` - Worker availability/health
- `grpc` - gRPC communication errors
- `etcd` - etcd coordination problems
- (none) - General troubleshooting

## Quick Diagnostic Commands

```bash
# Check if services are running
ps aux | grep -E "(manager|worker|mcp)"

# Check listening ports
lsof -i :50050  # Manager
lsof -i :50051  # Runner
lsof -i :50052  # Launcher
lsof -i :50053  # Remote

# gRPC health check
grpcurl -plaintext localhost:50050 grpc.health.v1.Health/Check

# etcd health
etcdctl --endpoints=localhost:32379 endpoint health

# List registered workers
etcdctl --endpoints=localhost:32379 get /workers --prefix
```

## Debug Checklist

- [ ] All services running?
- [ ] etcd healthy?
- [ ] Workers registered?
- [ ] Ports accessible?
- [ ] No error logs?
- [ ] Session transitions correct?
- [ ] Resources available?

## Common Issues

### Session Stuck in "Starting"

**Symptoms**: Session never transitions to "Running"

**Check**:

```bash
etcdctl --endpoints=localhost:32379 get /workers --prefix
grep "session\|assign" manager.log
```

**Causes**: No workers registered, worker crashed, etcd issues

**Fix**: Restart worker services, check etcd health

### Worker Not Registering

**Symptoms**: Workers not appearing in etcd

**Check**:

```bash
etcdctl --endpoints=localhost:32379 endpoint health
grep "register\|etcd" worker.log
```

**Causes**: etcd unreachable, wrong endpoints, lease failure

**Fix**: Verify etcd running, check ETCD_ENDPOINTS env var

### gRPC Connection Refused

**Symptoms**: "connection refused" errors

**Check**:

```bash
lsof -i :50050
nc -zv localhost 50050
```

**Causes**: Service not running, wrong port, firewall

**Fix**: Start service, check port config, check firewall

### Session Timeout

**Symptoms**: Sessions fail with timeout errors

**Check**:

```bash
grep "timeout\|deadline" manager.log
watch -n1 "etcdctl --endpoints=localhost:32379 get /sessions --prefix | head -20"
```

**Causes**: Slow MCP server startup, network latency, resource constraints

**Fix**: Increase timeouts, check MCP server startup time, add resources

## Service Management

```bash
cd src/mcp-engine

# Build and run unified (all services)
go build ./cmd/unified && ./unified

# Run individual services
go run ./cmd/manager &
go run ./cmd/worker-launcher &
go run ./cmd/worker-mcp-runner &

# Check status
etcdctl --endpoints=localhost:32379 get /workers --prefix --print-value-only | jq

# Force cleanup
etcdctl --endpoints=localhost:32379 del /workers --prefix
etcdctl --endpoints=localhost:32379 del /sessions --prefix
```

## When to Escalate

Escalate if:

- etcd data corruption suspected
- Persistent memory leaks
- gRPC protocol errors
- Intermittent failures without pattern

Collect before escalating:

- Service logs (last 1000 lines)
- etcd state dump
- System resource usage
- Network connectivity tests

## References

See `references/mcp-diagnostics.md` for detailed diagnostic procedures.
See `.claude/rules/mcp-engine.md` for MCP Engine patterns.