Troubleshooting Guide

This guide helps you diagnose and resolve common issues when using the MCP Registry Client.

Installation Issues

Python Version Compatibility

Problem: ImportError or syntax errors when importing the client.

Solution: Ensure you're using Python 3.12 or later:

python --version
# Should show Python 3.12.x or higher

If you need to upgrade Python, consider using pyenv or uv:

# Using uv
curl -LsSf https://astral.sh/uv/install.sh | sh
uv python install 3.12

# Using pyenv  
pyenv install 3.12.0
pyenv global 3.12.0

Missing Dependencies

Problem: ModuleNotFoundError for httpx or pydantic.

Solution: Install with all dependencies:

pip install mcp-registry-client
# or
uv pip install mcp-registry-client

For development dependencies:

pip install "mcp-registry-client[dev]"

Network Issues

Connection Refused

Problem: ConnectError when trying to reach the registry.

Symptoms:

httpx.ConnectError: [Errno 111] Connection refused

Solutions:

1. Check internet connection:

curl -I https://registry.modelcontextprotocol.io

1. Verify DNS resolution:

nslookup registry.modelcontextprotocol.io

1. Check firewall/proxy settings:

# Use custom proxy
from mcp_registry_client import RegistryClient

async with RegistryClient() as client:
    client._client.proxies = {
        "https://": "http://proxy.company.com:8080"
    }

SSL/TLS Issues

Problem: SSL verification errors.

Symptoms:

ssl.SSLCertVerificationError: certificate verify failed

Solutions:

1. Update certificates:

# On macOS
/Applications/Python\ 3.x/Install\ Certificates.command

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

1. Check system time: Ensure your system clock is correct.

2. Corporate network: Configure certificates for corporate networks:

import httpx
from mcp_registry_client import RegistryClient

# Custom client with cert bundle
async with RegistryClient() as client:
    client._client.verify = "/path/to/corporate-ca-bundle.pem"

Timeout Issues

Problem: Requests timing out.

Symptoms:

httpx.TimeoutException: timed out

Solutions:

1. Increase timeout:

from mcp_registry_client import RegistryClient

# Increase timeout to 60 seconds
async with RegistryClient(timeout=60.0) as client:
    result = await client.search_servers()

1. Check network stability:

ping -c 10 registry.modelcontextprotocol.io

1. Use retry logic (see Error Handling).

API Issues

Rate Limiting

Problem: HTTP 429 (Too Many Requests) errors.

Symptoms:

RegistryAPIError: Too Many Requests (429)

Solutions:

1. Implement backoff:

import asyncio
from mcp_registry_client import RegistryAPIError

async def search_with_backoff(client, **kwargs):
    for delay in [1, 2, 4, 8]:
        try:
            return await client.search_servers(**kwargs)
        except RegistryAPIError as e:
            if e.status_code == 429:
                await asyncio.sleep(delay)
            else:
                raise
    raise  # Final attempt failed

1. Reduce request frequency: Add delays between requests.

2. Cache results: Store responses to avoid repeated requests.

Server Not Found

Problem: Getting 404 errors for servers you expect to exist.

Solutions:

1. Check server name format:

# Correct format includes namespace
mcp-registry info "ai.waystation/gmail"

# Not just the server name
mcp-registry info gmail

1. Search first to find exact name:

mcp-registry search --name gmail

1. Check if server was recently added: The registry may not be immediately updated.

Invalid Response Format

Problem: ValidationError when processing responses.

Symptoms:

pydantic.ValidationError: 1 validation error for SearchResponse

Solutions:

1. Check registry status: The API might be returning unexpected data.

2. Update client: Ensure you're using the latest version:

pip install --upgrade mcp-registry-client

1. Report the issue: If the error persists, it might be an API change.

CLI Issues

Command Not Found

Problem: mcp-registry: command not found

Solutions:

1. Check installation:

pip show mcp-registry-client
pip install --force-reinstall mcp-registry-client

1. Check PATH: Ensure pip's bin directory is in your PATH:

python -m pip show -f mcp-registry-client | grep console_scripts

1. Use module syntax:

python -m mcp_registry_client.cli search

JSON Output Issues

Problem: Malformed JSON output or encoding errors.

Solutions:

1. Check terminal encoding:

echo $LANG
# Should include UTF-8

1. Redirect to file:

mcp-registry search --json > results.json

1. Use Python API for programmatic access instead of parsing CLI output.

Performance Issues

Slow Responses

Problem: Requests taking too long to complete.

Solutions:

1. Use connection pooling:

import httpx
from mcp_registry_client import RegistryClient

# Reuse client instance
client = RegistryClient()
async with client:
    # Multiple requests reuse connections
    result1 = await client.search_servers(name="server1")
    result2 = await client.search_servers(name="server2")

1. Implement caching:

from functools import lru_cache
import asyncio

@lru_cache(maxsize=128)
def _cache_key(name):
    return name

_cache = {}

async def cached_search(client, name=None):
    key = _cache_key(name)
    if key not in _cache:
        _cache[key] = await client.search_servers(name=name)
    return _cache[key]

1. Use specific searches: Search with name filters to reduce response size.

Memory Usage

Problem: High memory usage with large result sets.

Solutions:

1. Process results in chunks:

async def process_servers_chunked(client):
    result = await client.search_servers()
    for server in result.servers:
        # Process one server at a time
        await process_single_server(server)
        # Explicit cleanup if needed
        del server

1. Use generators when possible.

2. Limit result sets with specific search criteria.

Development Issues

Testing

Problem: Tests failing due to network dependencies.

Solutions:

1. Use httpx mock:

import pytest
import httpx
from mcp_registry_client import RegistryClient

@pytest.mark.asyncio
async def test_search_with_mock(httpx_mock):
    httpx_mock.add_response(
        method="GET",
        url="https://registry.modelcontextprotocol.io/v0/servers",
        json={"servers": [], "total": 0}
    )

    async with RegistryClient() as client:
        result = await client.search_servers()
        assert result.total == 0

1. Use pytest fixtures for common test data.

2. Test error conditions separately from happy path tests.

Type Checking

Problem: mypy errors with the client.

Solutions:

1. Update type hints:

from typing import Optional
from mcp_registry_client import RegistryClient, Server

async def get_server_info(name: str) -> Optional[Server]:
    async with RegistryClient() as client:
        return await client.get_server_by_name(name)

1. Use proper imports:

# Good
from mcp_registry_client import RegistryClient

# Avoid
import mcp_registry_client
client = mcp_registry_client.RegistryClient()

Getting Help

If you're still experiencing issues:

1. Check the logs: Enable debug logging:

import logging
logging.basicConfig(level=logging.DEBUG)

# Your client code here

1. Review error handling: See the Error Handling Guide.

2. Check for updates: Ensure you're using the latest version.

3. Report bugs: Create an issue with:

4. Python version
5. Client version
6. Full error traceback
7. Minimal reproduction code

Common Environment Variables

Set these environment variables to customize behavior:

# HTTP proxy
export HTTPS_PROXY=http://proxy.company.com:8080

# Certificate bundle
export REQUESTS_CA_BUNDLE=/path/to/ca-bundle.pem

# Debug logging
export PYTHONPATH=/path/to/debug/logging/config