mcp-connect

Troubleshooting Guide

Common issues and solutions for MCP Connect.

Installation Issues

OpenSSL Errors

Error: libssl.so.3: cannot open shared object file

Solution:

# Ubuntu/Debian
sudo apt install libssl3 libssl-dev

# Fedora/RHEL
sudo dnf install openssl-devel

# Or build with static OpenSSL
OPENSSL_STATIC=1 cargo build --release

Rust Version Errors

Error: error: edition 2021 is unstable

Solution: Update Rust

rustup update stable

Permission Errors

Error: Permission denied when running mcp-connect

Solution:

chmod +x target/release/mcp-connect
export PATH="$HOME/.cargo/bin:$PATH"

Configuration Issues

Configuration File Not Found

Error: No .mcp-connect.json found

Solution:

# Initialize configuration
mcp-connect init

# Or specify custom path
mcp-connect --config /path/to/config.json serve

Invalid JSON

Error: Failed to parse config file

Solution:

Validate JSON syntax: cat .mcp-connect.json | jq .
Check for trailing commas
Verify all quotes are properly escaped

Missing Environment Variables

Error: Environment variable not found: ${VAR_NAME}

Solution:

Check .env file exists in project root
Verify variable name matches exactly (case-sensitive)
Ensure no extra spaces: VAR=value not VAR = value
Restart the server after updating .env

Connection Issues

Connection Timeout

Error: Connection error: Timeout

Solutions:

Increase timeout:

{
  "servers": {
    "server": {
      "timeout": 60
    }
  }
}

Check network connectivity:
```
curl -I https://your-server.com/mcp
```
Verify server is reachable:
```
mcp-connect config test server-name
```

Authentication Errors

Error: Authentication error: 401 Unauthorized

Solutions:

Verify token is correct:

# Check .env file
cat .env | grep TOKEN

Test token manually:

curl -H "Authorization: Bearer $GITHUB_TOKEN" https://api.github.com/user

Check token format: Ensure no extra spaces or quotes
Verify token hasn’t expired: Regenerate if needed

SSL Certificate Errors

Error: SSL certificate verification failed

Solutions:

Check certificate validity: Verify server certificate is valid

Update CA certificates:

# Ubuntu/Debian
sudo apt update && sudo apt install ca-certificates

For development: Use proper certificates (not self-signed in production)

Server Issues

Server Not Starting

Error: Server fails to start or crashes

Solutions:

Check logs:
```
mcp-connect serve --debug
```
Validate configuration:
```
mcp-connect config validate
```
Test individual servers:
```
mcp-connect config test --all
```

No Servers Configured

Error: No servers configured in .mcp-connect.json

Solution:

# Add a server
mcp-connect config add github modelcontextprotocol/github-mcp-server

# Verify
mcp-connect config list

Server Not Appearing in IDE

Error: MCP Connect doesn’t appear in IDE’s MCP panel

Solutions:

Regenerate IDE config:
```
mcp-connect generate --ide vscode
```
Check binary path: Ensure path in IDE config is correct
Restart IDE: Fully restart the IDE (not just reload)
Check IDE logs: Look for errors in IDE’s developer console

Registry Issues

Registry Connection Failed

Error: Failed to connect to registry

Solutions:

Check internet connection: Ensure you can reach the registry
Verify registry URL: Check if the URL is correct

Test manually:

curl https://registry.modelcontextprotocol.io/v0.1/servers?limit=1

Server Not Found in Registry

Error: Server 'name' not found

Solutions:

Verify server name: Check spelling and format

Search registry:

mcp-connect registry search server-name

Check registry source: Use --source flag if using custom registry

Custom Registry Not Working

Error: Custom registry fails to connect

Solutions:

Verify registry URL: Ensure URL is accessible
Check API version: Verify API version path is correct
Test registry API: Verify it implements the expected API format
Check authentication: Some registries may require authentication

IDE Integration Issues

Zed Integration

Issues:

Server not appearing in context panel
Tools not available

Solutions:

Check Zed settings: Verify ~/.config/zed/settings.json has correct config
Check binary path: Use absolute path in configuration
Restart Zed: Fully quit and restart Zed
Check Zed logs: Look for errors in Zed’s developer console

VSCode/Cursor Integration

Issues:

MCP extension not recognizing server
Tools not appearing

Solutions:

Install MCP extension: Ensure MCP extension is installed
Check workspace settings: Verify .vscode/settings.json exists
Reload window: Use Ctrl+R / Cmd+R to reload
Check MCP output: View MCP extension output panel for errors
Verify binary path: Check path uses correct format (forward slashes on Windows)

Performance Issues

Slow Response Times

Solutions:

Check network: Test server response times
Increase timeout: For slow networks
Reduce retry attempts: If retries are causing delays
Check server load: Remote servers may be slow

High Memory Usage

Solutions:

Monitor processes: Check for memory leaks
Reduce concurrent servers: Limit number of active servers
Restart server: Periodically restart to free memory

Debugging Commands

Enable Debug Mode

mcp-connect serve --debug

Verbose Logging

mcp-connect serve --log-level trace

Test Individual Components

# Test configuration
mcp-connect config validate

# Test server connection
mcp-connect config test server-name

# Test all servers
mcp-connect config test --all

# Test registry
mcp-connect registry search test

Getting Help

Check Logs

Always check logs first:

mcp-connect serve --debug 2>&1 | tee mcp-connect.log

Collect Information

When reporting issues, include:

MCP Connect version: mcp-connect --version
Configuration file (sanitized): mcp-connect config list
Error messages: Full error output
System information: OS, Rust version
Steps to reproduce

Common Resources

Documentation: See other docs in docs/ directory
Issues: Check GitHub Issues for similar problems
Examples: Review examples/ directory for usage patterns

Prevention Tips

Validate before committing: Always run mcp-connect config validate
Test after changes: Use mcp-connect config test --all after adding servers
Keep backups: Backup .mcp-connect.json before major changes
Monitor logs: Regularly check logs for warnings
Update regularly: Keep MCP Connect updated to latest version