Troubleshooting

Common issues and solutions for registry connectivity, authentication, sandbox errors, cache corruption, and platform-specific problems.

  7 min read  

This page covers the most common issues encountered when using the MCP Client, organized by category. Start with mcp doctor to diagnose system-level problems, then refer to the relevant section below.

First Steps: Run the Diagnostics

Before investigating specific issues, run the built-in diagnostic tool:

mcp doctor --verbose

This checks registry connectivity, sandbox capabilities, cache health, and configuration validity. The output identifies problems with clear descriptions and suggested fixes.

# Also attempt automatic fixes for common issues
mcp doctor --fix

Registry Connection Problems

“connection refused” or “connection timed out”

Symptom: Commands that contact the registry (run, pull, info) fail with connection errors.

Causes and solutions:

  1. Wrong registry URL. Verify your configured registry:

    mcp doctor --registry https://registry.mcp-hub.io

    Check your config file:

    cat ~/.mcp/config.yaml | grep url

  2. Local registry not running. If using a local development setup:

    # Check if the registry container is running
docker compose ps registry

# Start it if needed
make dev-registry

    The local registry runs on port 8081 by default.

  3. Firewall or proxy blocking. If you are behind a corporate firewall, ensure HTTPS traffic to the registry domain is permitted. Set proxy environment variables if needed:

    export HTTPS_PROXY=http://proxy.corp.example.com:8080
mcp pull acme/[email protected]

“TLS certificate error” or “x509: certificate signed by unknown authority”

Symptom: TLS handshake fails when connecting to the registry.

Solutions:

  1. Self-signed certificates (local development). Disable TLS verification:

    # ~/.mcp/config.yaml
registry:
  tls_verify: false

  2. Missing CA certificates. Ensure your system CA bundle is up to date:

    # macOS
brew install ca-certificates

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

  3. Corporate CA. Add your corporate root CA to the system trust store.

“429 Too Many Requests”

Symptom: Registry returns rate limit errors.

Solution: The client automatically respects 429 responses with exponential backoff (up to 3 retries). If you consistently hit rate limits:

  • Pre-populate the cache with mcp pull during off-peak times
  • Use the MCP_REGISTRY_TOKEN for authenticated access, which typically has higher rate limits
  • Contact your MCP Hub administrator to increase rate limits for your organization

Authentication Failures

“authentication required” or “401 Unauthorized”

Symptom: Registry rejects your request because you are not authenticated.

Solutions:

  1. Log in first:

    mcp login

  2. Token expired. Tokens are not auto-refreshed. Re-authenticate:

    mcp logout
mcp login

  3. Wrong registry. Tokens are stored per registry URL. Ensure you are logged in to the correct registry:

    mcp login --registry https://registry.mcp-hub.io

“403 Forbidden”

Symptom: You are authenticated but lack permission to access the resource.

Solutions:

  1. Insufficient scope. Your token may not have the required scope for the operation. Contact your organization admin to adjust your permissions.

  2. Organization policy. Enterprise organizations may restrict access to certain packages. Check with your admin.

  3. Package is private. Ensure you have access to the package’s namespace.

“auth.json permission denied”

Symptom: The client cannot read or write the auth token file.

Solution: Fix file permissions:

chmod 600 ~/.mcp/auth.json
chmod 700 ~/.mcp

If the file is owned by root (from running the client with sudo), fix ownership:

sudo chown $(whoami) ~/.mcp/auth.json

CI/CD Token Issues

Symptom: Authentication works locally but fails in CI/CD.

Solutions:

  1. Use environment variable instead of auth.json:

    export MCP_REGISTRY_TOKEN="$CI_MCP_TOKEN"
mcp pull acme/[email protected]

  2. Token not set. Verify the secret is available in your CI environment:

    # Debug: check if the variable is set (do not print the value)
[ -n "$MCP_REGISTRY_TOKEN" ] && echo "Token is set" || echo "Token is NOT set"

Sandbox Errors

“cgroups v2 not available”

Symptom: On Linux, the client warns that cgroups v2 is not available.

Solutions:

  1. Enable cgroups v2. On systemd-based systems:

    # Check current cgroup version
mount | grep cgroup

# Enable cgroups v2 (requires reboot)
sudo grubby --update-kernel=ALL --args="systemd.unified_cgroup_hierarchy=1"
sudo reboot

  2. Use Docker. Run the MCP Client inside a Docker container where cgroups v2 is typically available:

    docker run --rm -it mcphub/mcp-client:latest doctor

  3. Proceed with rlimits only. The client falls back to rlimits, which provide basic resource limiting but without the full cgroups v2 guarantees. This is acceptable for development.

“permission denied: seccomp” or “operation not permitted”

Symptom: The client cannot install seccomp filters.

Solutions:

  1. Running in an unprivileged container. Some container runtimes block seccomp installation. Add the --security-opt seccomp=unconfined flag to Docker, or use a custom seccomp profile that allows the MCP Client’s required syscalls.

  2. Kernel too old. seccomp BPF requires Linux 3.17+. Check your kernel version:

    uname -r

“Landlock not available”

Symptom: Filesystem isolation falls back to basic bind mounts.

Solution: Landlock requires Linux 5.13+. Check your kernel:

uname -r

Upgrade if needed. The client works without Landlock but with weaker filesystem isolation.

“network namespace: operation not permitted”

Symptom: Network isolation fails on Linux.

Solutions:

  1. Missing CAP_NET_ADMIN. The client needs the CAP_NET_ADMIN capability or root access to create network namespaces:

    # Grant capability to the binary (one-time)
sudo setcap cap_net_admin=ep $(which mcp)

  2. Kernel restriction. Check if unprivileged user namespaces are enabled:

    cat /proc/sys/kernel/unprivileged_userns_clone
# Should be 1

  3. Disable network isolation. If not needed, allow network access:

    mcp run acme/[email protected] --network allow

“resource limit exceeded” (exit code 137)

Symptom: The MCP server is killed with exit code 137 (OOM).

Solutions:

  1. Increase memory limit:

    mcp run acme/[email protected] --max-memory 1g

  2. Check actual usage. Run with verbose logging to see resource consumption:

    mcp run acme/[email protected] --verbose

  3. Memory leak in MCP server. The MCP server itself may have a memory leak. Report the issue to the package publisher.

Cache Corruption

“digest mismatch” or “integrity validation failed”

Symptom: A cached artifact fails SHA-256 validation.

Solutions:

  1. Remove the corrupted entry:

    mcp cache rm acme/[email protected]

  2. Force re-download:

    mcp pull acme/[email protected] --force

  3. Clear entire cache (nuclear option):

    mcp cache rm --all --force

“cache directory not writable”

Symptom: The client cannot write to the cache directory.

Solutions:

  1. Fix permissions:

    chmod 755 ~/.mcp/cache
chown -R $(whoami) ~/.mcp/cache

  2. Disk full. Check available space:

    df -h ~/.mcp/cache

    Clear old artifacts:

    mcp cache rm --older-than 720h

  3. Custom cache directory. If the default location is problematic, change it:

    export MCP_CACHE_DIR=/tmp/mcp-cache
mcp pull acme/[email protected]

“stale cache” or unexpected behavior after registry update

Symptom: The client uses an old version of a package even though a new version was published.

Solution: The client caches manifests with a TTL (default: 24 hours). Force a fresh resolution:

mcp pull acme/[email protected] --force

Bundles are content-addressed and never become stale – if the content matches the digest, it is correct by definition. Only metadata resolution can become stale.

Platform-Specific Issues

macOS

“mcp doctor reports DEVELOPMENT ONLY”

This is expected. macOS does not support network namespaces, cgroups, or seccomp. The client uses rlimits and UNIX permissions as best-effort alternatives. For production use with untrusted packages, use Linux.

“ulimit: open files: cannot modify limit”

macOS imposes a low default limit for open file descriptors. Increase it:

ulimit -n 4096

To make this permanent, see Apple’s documentation on launchd.conf.

“binary not found” after make install

Ensure $GOPATH/bin is in your PATH:

export PATH=$PATH:$(go env GOPATH)/bin

Windows

“sandbox capabilities: NOT AVAILABLE”

Windows support is minimal. Job Objects provide basic resource limits but no network or filesystem isolation. For production use, run the MCP Client inside WSL2 (which provides a Linux kernel).

PowerShell execution policy

If running scripts that invoke mcp, ensure the PowerShell execution policy allows it:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Linux

“mcp: permission denied”

If the binary lacks execute permission:

chmod +x ./mcp

“CGO_ENABLED required”

The MCP Client is built with CGO_ENABLED=0 by default. If you encounter CGO-related errors, ensure you are using the official build command:

make build

Getting Help

If you cannot resolve an issue:

  1. Collect diagnostics:

    mcp doctor --json > diagnostics.json
mcp --version
uname -a
go version

  2. Check audit logs for details about failures:

    cat ~/.mcp/audit.log | tail -20

  3. Enable debug logging for maximum detail:

    MCP_LOG_LEVEL=debug mcp run acme/[email protected] 2>debug.log

  4. File an issue on the MCP Hub Platform repository with the diagnostics output and debug logs.