Troubleshooting Guide

This guide covers common issues you might encounter when using MCP Foxxy Bridge and how to resolve them.

Common Issues

Server Connection Issues

MCP servers fail to connect

Symptoms:

Bridge starts but servers show "failed" status
Error messages about connection timeouts
Tools are not available

🔍 Quick Diagnosis:

# Check server status
foxxy-bridge server server-status

# List configured servers
foxxy-bridge mcp mcp-list

# View detailed server information
foxxy-bridge mcp mcp-show github

Possible Causes and Solutions:

Incorrect command or arguments

# Check if the command works directly
npx -y @modelcontextprotocol/server-github

# If command is wrong, remove and re-add server
foxxy-bridge mcp remove github
foxxy-bridge mcp add github "npx" "-y" "@modelcontextprotocol/server-github"

Missing dependencies

# Install missing MCP servers
npm install -g @modelcontextprotocol/server-github
npm install -g @modelcontextprotocol/server-filesystem

# Or use npx to auto-install
npx -y @modelcontextprotocol/server-github

Environment variables not set

# Check required environment variables
echo $GITHUB_TOKEN

# Set if missing
export GITHUB_TOKEN=your_token_here

# Update server configuration
foxxy-bridge mcp remove github
foxxy-bridge mcp add github "npx" "-y" "@modelcontextprotocol/server-github" \
  --env GITHUB_TOKEN "${GITHUB_TOKEN}"

Permission issues

# Check file permissions
ls -la /path/to/directory

# Fix permissions if needed
chmod 755 /path/to/directory

Async context manager errors

Error message: "_AsyncGeneratorContextManager can't be used in 'await' expression"

Solution: This is a known issue that has been fixed. Update to the latest version of MCP Foxxy Bridge:

uv tool upgrade mcp-foxxy-bridge

Port and Network Issues

Port already in use

Symptoms:

Bridge fails to start
Error about port being in use

Solution: The bridge automatically finds available ports. If you need a specific port, ensure nothing else is using it:

# Check what's using the port
lsof -i :8080

# Kill the process if needed
kill -9 <PID>

# Or use a different port
mcp-foxxy-bridge --bridge-config config.json --port 8081

Can't connect to bridge from client

Symptoms:

MCP client can't connect to bridge
Connection refused or timeout errors

Solutions:

Check if bridge is running
```
curl http://localhost:8080/status
```
Verify correct endpoint

MCP clients should connect to /sse:
```
http://localhost:8080/sse
```

Check host binding

# For local access only (default)
mcp-foxxy-bridge --bridge-config config.json --host 127.0.0.1

# For network access
mcp-foxxy-bridge --bridge-config config.json --host 0.0.0.0

Firewall issues

# Allow port through firewall (Linux)
sudo ufw allow 8080

# Check firewall rules
sudo ufw status

Configuration Issues

Environment variable expansion not working

Symptoms:

Variables like ${GITHUB_TOKEN} appear literally in logs
Authentication failures

Solutions:

Check variable syntax

{
  "env": {
    "TOKEN": "${GITHUB_TOKEN}",          // ✅ Correct
    "TOKEN": "$GITHUB_TOKEN",            // ❌ Wrong
    "TOKEN": "${GITHUB_TOKEN:default}"   // ✅ With default
  }
}

Verify environment variables are set

# Check if variable exists
printenv | grep GITHUB_TOKEN

# Set if missing
export GITHUB_TOKEN=your_token_here

Configuration file not found

Error: "Configuration file not found"

Solutions:

Using CLI (recommended)

# Initialize configuration if missing
foxxy-bridge config init

# Check configuration location
foxxy-bridge config config-show

# Validate configuration
foxxy-bridge config validate

Legacy file-based approach

# Use absolute path
mcp-foxxy-bridge --bridge-config /full/path/to/config.json

# Or relative to current directory
ls -la config.json

Check file permissions

ls -la config.json
chmod 644 config.json

Invalid JSON configuration

Error: "Failed to parse configuration"

Solutions:

Validate JSON syntax

# Check JSON validity
python -m json.tool config.json

# Or use jq
jq . config.json

Common JSON errors
- Missing commas between objects
- Trailing commas (not allowed in JSON)
- Unquoted keys or values
- Mismatched brackets

Tool and Resource Issues

Tools not showing up

Symptoms:

Bridge status shows servers connected
But list_tools() returns empty or partial results

Solutions:

Check server status

curl -s http://localhost:8080/status | jq '.server_instances'

Verify server capabilities

Test individual servers manually:

# Test GitHub server directly
npx -y @modelcontextprotocol/server-github

Check namespacing configuration

{
  "mcpServers": {
    "github": {
      "toolNamespace": "github",  // Tools will have 'github.' prefix
      "enabled": true
    }
  }
}

Tool calls fail

Error: "Tool 'toolname' not found"

Solutions:

Check tool name format

With namespacing enabled, use:

github.search_repositories  // ✅ Correct
search_repositories         // ❌ Missing namespace

Verify server connection

curl -s http://localhost:8080/status | jq '.server_instances.github.status'

Check server logs

Run bridge with debug mode:

mcp-foxxy-bridge --bridge-config config.json --debug

Docker Issues

Container fails to start

Solutions:

Check Docker build
```
docker build -t mcp-foxxy-bridge .
```

Verify volume mounts

# Ensure config file exists
ls -la ./config.json

# Use absolute paths in volume mounts
docker run -v $(pwd)/config.json:/app/config/config.json:ro ...

Check environment variables

# Pass environment variables correctly
docker run -e GITHUB_TOKEN=your_token ...

Permission denied in container

Solutions:

Fix file permissions
```
chmod 644 config.json
```
Check Docker user

The container runs as a non-root user. Ensure files are readable.

Performance Issues

High memory usage

Symptoms:

Bridge uses excessive memory
Out of memory errors

Solutions:

Check server health

Unhealthy servers may cause memory leaks:

curl -s http://localhost:8080/status | \\
  jq '.server_instances[] | select(.status != "connected")'

Reduce server count

Disable unused servers:

{
  "mcpServers": {
    "unused_server": {
      "enabled": false
    }
  }
}

Adjust timeouts

{
  "mcpServers": {
    "server_name": {
      "timeout": 30,           // Shorter timeout
      "retryAttempts": 2       // Fewer retries
    }
  }
}

Slow response times

Solutions:

Check individual server performance

Test servers directly to identify slow ones.

Optimize configuration

{
  "bridge": {
    "failover": {
      "enabled": true,
      "maxFailures": 2,        // Fail faster
      "recoveryInterval": 30000
    }
  }
}

OAuth and SSL Issues

SSL Certificate Verification Errors

Error: SSL: CERTIFICATE_VERIFY_FAILED or similar SSL errors

Solutions:

For production environments (keep SSL verification enabled):
```
{
  "oauth": {
    "enabled": true,
    "issuer": "https://auth.example.com",
    "verify_ssl": true  // Default: always verify certificates
  }
}
```
- Ensure valid SSL certificates are installed
- Check certificate chain is complete
- Verify system CA certificates are up to date
For development environments (self-signed certificates):
```
{
  "oauth": {
    "enabled": true,
    "issuer": "https://dev.local:8443",
    "verify_ssl": false  // ONLY for development
  }
}
```
⚠️ Warning: Only disable SSL verification in development. The bridge will log warnings when SSL is disabled.

Check certificate details:

# Check certificate validity
openssl s_client -connect auth.example.com:443 -servername auth.example.com < /dev/null

# View certificate details
openssl s_client -connect auth.example.com:443 -showcerts < /dev/null | openssl x509 -text

OAuth Authentication Failures

Error: OAuth preflight check failed or OAuth discovery failed

Solutions:

Check OAuth preflight logs (errors are detected immediately):

foxxy-bridge --debug server start
# Look for:
# ERROR: OAuth preflight check failed for server 'example'
# ERROR: OAuth discovery failed for all endpoints

Verify OAuth discovery attempts (bridge tries multiple endpoints):

# Server-specific discovery
curl https://mcp.example.com/sse/.well-known/openid_configuration
curl https://mcp.example.com/sse/.well-known/oauth-authorization-server

# Base URL discovery
curl https://mcp.example.com/.well-known/openid_configuration
curl https://mcp.example.com/.well-known/oauth-authorization-server

Manual OAuth configuration (if discovery fails):

{
  "oauth": {
    "enabled": true,
    "issuer": "https://auth.example.com",  // Specify issuer manually
    "verify_ssl": true
  }
}

Use CLI OAuth commands:

# Check OAuth status
foxxy-bridge oauth status

# Force re-authentication
foxxy-bridge oauth login production-api --force

# Clear stored tokens
foxxy-bridge oauth logout production-api

Check OAuth callback port:

{
  "bridge": {
    "oauth_port": 8090  // Ensure port is available
  }
}

# Check if port is in use
lsof -i :8090
netstat -tlnp | grep 8090

HTTP/2 Connection Issues

Error: HTTP/2 protocol error or connection drops

Solutions:

Server doesn't support HTTP/2:
- The bridge automatically falls back to HTTP/1.1
- No configuration needed
Proxy interference:
- Some proxies don't support HTTP/2
- Check proxy configuration if using one

Debug HTTP/2 issues:

# Test HTTP/2 support
curl -I --http2 https://api.example.com

Debugging Techniques

Enable Debug Logging

🎯 Using CLI (recommended):

# Start with debug logging
foxxy-bridge server start --log-level debug

# View server logs
foxxy-bridge mcp logs github --follow

# Check daemon status with debug info
foxxy-bridge server server-status --format json

📄 Legacy approach:

mcp-foxxy-bridge --bridge-config config.json --debug

This will show:

Server connection attempts
Tool routing decisions
Error details and stack traces

Check Server Status

🎯 Using CLI:

# Check overall bridge status
foxxy-bridge server server-status

# List all servers and their status
foxxy-bridge mcp mcp-list --format table

# View specific server details
foxxy-bridge mcp mcp-show github --format json

# Check OAuth status
foxxy-bridge oauth status

# Initiate OAuth login
foxxy-bridge oauth login <server>

# Clear OAuth tokens
foxxy-bridge oauth logout <server>

📄 REST API approach:

# Get detailed status
curl -s http://localhost:8080/status | python -m json.tool

# Monitor status continuously
watch -n 2 'curl -s http://localhost:8080/status | jq .server_instances'

Test Individual Components

Test MCP servers directly

# Run server in isolation
npx -y @modelcontextprotocol/server-github

Test bridge connectivity

# Check if bridge responds
curl -v http://localhost:8080/sse

Test configuration parsing

# Validate config syntax
python -c "import json; json.load(open('config.json'))"

Common Debug Patterns

Connection issues: Check command, args, and environment variables
Tool routing issues: Verify namespacing and server status
Performance issues: Check server health and timeout settings
Configuration issues: Validate JSON and file permissions

Getting Additional Help

Collecting Information

When seeking help, include:

Bridge version
```
mcp-foxxy-bridge --version
```

Configuration file (remove sensitive data)

# Sanitize your config
cat config.json | sed 's/ghp_[^"]*/"<redacted>"/g'

Status output

curl -s http://localhost:8080/status | jq .

Debug logs

mcp-foxxy-bridge --bridge-config config.json --debug 2>&1 | head -50

Environment details
- Operating system and version
- Python version (python --version)
- Node.js version (node --version)
- UV version (uv --version)

Where to Get Help

GitHub Issues: https://github.com/billyjbryant/mcp-foxxy-bridge/issues
Configuration Guide: configuration.md
API Reference: api.md
Architecture Overview: architecture.md

Before Opening an Issue

Check existing issues for similar problems
Verify you're using the latest version
Test with minimal configuration
Collect debug information as described above

FAQ

Q: Why do I get "port already in use" errors?

A: The bridge automatically finds available ports starting from your requested port. If you see this error, another process is likely using a range of ports. Try a different port range or kill the conflicting process.

Q: My tools have weird prefixes like "github.search_repositories"

A: This is namespacing to prevent conflicts between servers. You can:

Use the full namespaced name in tool calls
Disable namespacing with "toolNamespace": null
Customize the namespace with "toolNamespace": "custom"

Q: Some servers connect but others don't

A: Check each server individually:

Verify the command works outside the bridge
Check environment variables are set
Look at debug logs for specific error messages
Ensure dependencies are installed

Q: The bridge works locally but not in Docker

A: Common Docker issues:

File permissions (use chmod 644 on config files)
Environment variables not passed correctly
Volume mounts using relative paths
Network configuration preventing connections

Q: Can I use HTTP instead of SSE?

A: The bridge supports both SSE and StreamableHTTP transports. Most MCP clients use SSE by default, but you can use the HTTP endpoint if your client supports it.

FilesExpand file tree

troubleshooting.md

Latest commit

History

troubleshooting.md

File metadata and controls

Troubleshooting Guide

Common Issues

Server Connection Issues

MCP servers fail to connect

Async context manager errors

Port and Network Issues

Port already in use

Can't connect to bridge from client

Configuration Issues

Environment variable expansion not working

Configuration file not found

Invalid JSON configuration

Tool and Resource Issues

Tools not showing up

Tool calls fail

Docker Issues

Container fails to start

Permission denied in container

Performance Issues

High memory usage

Slow response times

OAuth and SSL Issues

SSL Certificate Verification Errors

OAuth Authentication Failures

HTTP/2 Connection Issues

Debugging Techniques

Enable Debug Logging

Check Server Status

Test Individual Components

Common Debug Patterns

Getting Additional Help

Collecting Information

Where to Get Help

Before Opening an Issue

FAQ

Q: Why do I get "port already in use" errors?

Q: My tools have weird prefixes like "github.search_repositories"

Q: Some servers connect but others don't

Q: The bridge works locally but not in Docker

Q: Can I use HTTP instead of SSE?