Frequently Asked Questions

Frequently Asked Questions

Find answers to the most commonly asked questions about MCP Client Tester, the Model Context Protocol, and effective testing strategies.

General Questions

What is MCP Client Tester?

MCP Client Tester is a comprehensive testing and debugging tool specifically designed for the Model Context Protocol (MCP). It acts as both an MCP server and client, providing detailed protocol analysis, client capability detection, and performance monitoring for MCP implementations.

Key capabilities:

• Protocol compliance testing
• Client compatibility validation
• Performance benchmarking
• Real-time protocol monitoring
• Automated test suite execution

Who should use MCP Client Tester?

MCP Client Tester is designed for:

• MCP Server Developers: Test server implementations against various clients
• MCP Client Developers: Validate client protocol compliance and feature support
• System Integrators: Ensure MCP-based systems work correctly together
• QA Engineers: Automate MCP testing in CI/CD pipelines
• DevOps Teams: Monitor MCP connections in production environments

How does MCP Client Tester differ from other testing tools?

MCP Client Tester is purpose-built for MCP testing with several unique advantages:

• Protocol-Specific: Deep understanding of MCP message formats and semantics
• Transport Agnostic: Supports all MCP transport protocols (STDIO, HTTP, SSE, streaming)
• Client Detection: Automatically identifies and profiles MCP clients
• Real-time Monitoring: Live protocol inspection and debugging
• Comprehensive Reporting: Detailed test reports and compatibility matrices

Installation & Setup

Do I need Docker to run MCP Client Tester?

While Docker is the recommended deployment method, it’s not strictly required. However, Docker provides:

• Easy Setup: One-command deployment with all dependencies
• Consistency: Same environment across different machines
• Isolation: No conflicts with existing software
• Scalability: Easy to scale services for load testing

Alternative installations:

# Manual installation (not recommended for beginners)
python -m pip install -r backend/requirements.txt
npm install # in frontend directory
npm install # in docs directory

Why can’t I access the web interface after installation?

Common causes and solutions:

1. Domain Resolution Issues

   # Check if domain resolves
   nslookup mcp-tester.local
   
   # Add to /etc/hosts if needed
   echo "127.0.0.1    mcp-tester.local" | sudo tee -a /etc/hosts

2. Port Conflicts

   # Check if ports are in use
   sudo lsof -i :80
   sudo lsof -i :443
   
   # Change ports in .env if needed
   PORT_HTTP=8080
   PORT_HTTPS=8443

3. Service Health Issues

   # Check service status
   docker-compose ps
   
   # View logs for errors
   docker-compose logs frontend

Can I use MCP Client Tester in production?

Yes, but with considerations:

Development/Testing Environments: ✅ Fully supported

• Complete protocol logging
• Debug information exposed
• Development-friendly error messages

Production Monitoring: ✅ Supported with configuration

• Disable debug logging (DEBUG=false)
• Enable authentication (API_KEYS=your-keys)
• Use production logging levels (LOG_LEVEL=INFO)
• Implement proper security measures

Production Load Testing: ⚠️ Use with caution

• Can generate significant load on target systems
• May expose sensitive protocol data in logs
• Ensure proper access controls

Protocol & Compatibility

Which MCP clients are supported?

MCP Client Tester supports all MCP-compliant clients. Tested clients include:

Fully Supported:

• Claude Desktop (1.2.x, 1.3.x)
• FastMCP Client (2.12+)
• Official Python MCP SDK
• Official TypeScript MCP SDK

Partial Support:

• Custom MCP implementations (varies by compliance level)
• Legacy MCP versions (limited feature support)

What if my MCP client isn’t detected properly?

Client detection is automatic but can be improved:

1. Enable Enhanced Detection

   {
     "config": {
       "auto_detect_client": true,
       "detailed_client_analysis": true,
       "enable_feature_probing": true
     }
   }

2. Manual Client Registration

   curl -X POST "https://api.mcp-tester.local/api/v1/clients/register" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "My Custom Client",
       "version": "1.0.0",
       "user_agent": "MyClient/1.0.0",
       "capabilities": {...}
     }'

3. Review Detection Logs

   # Check detection process
   docker-compose logs backend | grep -i "client.*detect"

Does MCP Client Tester support all transport protocols?

Yes, MCP Client Tester supports all standard MCP transport protocols:

Transport	Support Level	Use Cases
STDIO	✅ Full	Claude Desktop, local development
HTTP	✅ Full	Web-based clients, REST APIs
Server-Sent Events	✅ Full	Real-time web applications
HTTP Streaming	✅ Full	Low-latency bidirectional communication

Transport-Specific Features:

• Protocol message interception and logging
• Connection lifecycle monitoring
• Transport-specific error handling
• Performance metrics per transport type

Can I test custom MCP protocol extensions?

MCP Client Tester supports testing custom extensions:

Standard Extensions: ✅ Automatic support

• Custom tools and resources
• Additional message types
• Extended capabilities

Protocol Modifications: ⚠️ Limited support

• May require configuration adjustments
• Custom validation rules may be needed
• Compatibility reporting may be incomplete

Best Practice: Stick to MCP specification for maximum compatibility.

Testing & Development

How do I test my MCP server implementation?

Follow this testing workflow:

1. Start MCP Client Tester

   docker-compose up -d

2. Create Test Session

   curl -X POST "https://api.mcp-tester.local/api/v1/sessions" \
     -d '{"name": "My Server Test", "transport": "http"}'

3. Point Your Server to the provided test endpoint

4. Run Test Suite

   # Automated testing
   python scripts/test_mcp_server.py --server-url http://localhost:8001

5. Review Results in the web interface or export data for analysis

What should I test in my MCP implementation?

Essential Test Areas:

1. Protocol Compliance

   • JSON-RPC 2.0 message format
   • Required method implementations
   • Error response handling

2. Feature Functionality

   • Tool registration and execution
   • Resource access and reading
   • Prompt templates and parameters

3. Error Handling

   • Invalid request handling
   • Resource not found scenarios
   • Permission denied cases

4. Performance

   • Response time benchmarks
   • Concurrent request handling
   • Memory usage patterns

5. Client Compatibility

   • Different client behavior patterns
   • Feature support variations
   • Transport protocol differences

How do I automate MCP testing in CI/CD?

GitHub Actions Example:

name: MCP Testing
on: [push, pull_request]

jobs:
  mcp-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Start MCP Client Tester
        run: docker-compose up -d

      - name: Wait for services
        run: |
          timeout 60s bash -c 'until curl -f http://localhost/health; do sleep 1; done'

      - name: Run MCP Protocol Tests
        run: |
          python test_runner.py --server-url http://localhost:8001 \
                               --output junit-results.xml

      - name: Upload Test Results
        uses: actions/upload-artifact@v3
        with:
          name: mcp-test-results
          path: junit-results.xml

Integration Points:

• REST API for programmatic control
• Export formats (JSON, JUnit XML, HAR)
• Exit codes for pass/fail determination
• Docker-based deployment for consistency

Can I use MCP Client Tester for load testing?

Yes, MCP Client Tester includes built-in load testing capabilities:

Load Test Configuration:

{
  "duration_seconds": 300,
  "requests_per_second": 50,
  "concurrent_clients": 10,
  "target_tools": ["search", "process_data"],
  "ramp_up_seconds": 30
}

Metrics Collected:

• Request/response latency (avg, p95, p99)
• Throughput (requests per second)
• Error rates by type
• Resource utilization
• Connection success rates

Load Test Limitations:

• Designed for protocol testing, not infrastructure stress testing
• Focus on MCP-specific scenarios rather than raw performance
• Consider impact on target systems

Performance & Troubleshooting

Why are my tests running slowly?

Common performance issues and solutions:

1. Resource Constraints

   # Check Docker resource usage
   docker stats
   
   # Increase Docker memory/CPU limits
   # In Docker Desktop: Settings → Resources

2. Database Performance

   # Check database connection
   docker-compose logs postgres
   
   # Consider using external database for production
   DATABASE_URL=postgresql://user:pass@external-db:5432/mcp_tester

3. Network Latency

   # Test local network performance
   ping mcp-tester.local
   
   # Use localhost for local testing
   DOMAIN=localhost

4. Logging Overhead

   # Reduce log verbosity for performance testing
   MCP_LOG_LEVEL=WARN
   DEBUG=false

How do I debug connection issues?

Systematic Debugging Process:

1. Check Service Health

   docker-compose ps
   curl https://api.mcp-tester.local/health

2. Review Connection Logs

   docker-compose logs backend | grep -i "connection\|error"

3. Test Transport Directly

   # HTTP transport
   curl -v "https://api.mcp-tester.local/mcp" \
     -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'
   
   # WebSocket transport
   wscat -c "wss://api.mcp-tester.local/ws"

4. Verify Client Configuration

   • Check endpoint URLs
   • Validate authentication credentials
   • Confirm transport protocol selection

5. Network Troubleshooting

   # Test DNS resolution
   nslookup mcp-tester.local
   
   # Check port accessibility
   telnet mcp-tester.local 443
   
   # Verify SSL certificate
   openssl s_client -connect mcp-tester.local:443

What data does MCP Client Tester collect?

Protocol Data:

• Complete message logs (requests, responses, notifications)
• Timing information (send time, response time, processing time)
• Error details and stack traces
• Client capability information

Session Metadata:

• Session configuration and parameters
• Client detection results
• Performance metrics and statistics
• Test results and outcomes

Privacy Considerations:

• All data stored locally by default
• No external data transmission
• Configurable data retention policies
• Export capabilities for data analysis

Data Security:

• Optional authentication for API access
• Configurable access controls
• Audit logging for administrative actions
• Data encryption options for sensitive environments

Advanced Usage

Can I extend MCP Client Tester functionality?

Yes, MCP Client Tester is designed for extensibility:

Custom Test Scenarios:

# Add custom test scenarios
class CustomMCPTests(TestSuite):
    async def test_custom_workflow(self):
        # Your custom test logic
        result = await self.call_tool("my_custom_tool", {...})
        self.assert_valid_response(result)

Plugin Development:

• REST API for external integrations
• WebSocket API for real-time updates
• Export plugins for custom reporting formats
• Custom client detection rules

Configuration Extensions:

# Custom configuration in .env
CUSTOM_TEST_MODULES=my_company.mcp_tests,another_module
ENABLE_EXPERIMENTAL_FEATURES=true

How do I integrate with existing monitoring systems?

Prometheus Metrics:

# Enable metrics endpoint
ENABLE_METRICS=true

# Scrape endpoint
curl http://localhost:8000/metrics

Log Integration:

# Forward logs to external systems
logging:
  driver: syslog
  options:
    syslog-address: "udp://logstash.company.com:514"
    tag: "mcp-client-tester"

API Integration:

# Custom monitoring integration
import requests

def check_mcp_health():
    response = requests.get("https://api.mcp-tester.local/health")
    return response.status_code == 200

Can I use MCP Client Tester for compliance testing?

Yes, MCP Client Tester supports compliance validation:

Standards Compliance:

• MCP specification adherence testing
• JSON-RPC 2.0 compliance validation
• Transport protocol standard conformance

Custom Compliance Rules:

{
  "compliance_rules": {
    "required_methods": ["initialize", "tools/list"],
    "forbidden_methods": ["deprecated_method"],
    "parameter_validation": true,
    "response_format_validation": true
  }
}

Compliance Reporting:

• Detailed compliance matrices
• Gap analysis and recommendations
• Pass/fail criteria customization
• Automated compliance scoring

Getting Help

Where can I find more documentation?

Official Documentation:

• API Reference: Complete REST API documentation
• Protocol Guide: Detailed MCP protocol explanations
• Examples: Step-by-step usage examples
• Troubleshooting: Common issues and solutions

Community Resources:

• GitHub Issues: Bug reports and feature requests
• Discussions: Community Q&A and best practices
• Examples Repository: Real-world usage patterns

How do I report bugs or request features?

Bug Reports:

1. Check existing issues first
2. Include detailed reproduction steps
3. Provide environment information (OS, Docker version, etc.)
4. Include relevant log files and session exports
5. Specify MCP client/server versions

Feature Requests:

1. Describe the use case and business value
2. Provide examples of desired behavior
3. Consider backwards compatibility
4. Suggest implementation approaches if possible

Contributing:

• Pull requests welcome for bug fixes
• Feature PRs should include tests and documentation
• Follow existing code style and conventions
• Update documentation as needed

Is commercial support available?

MCP Client Tester is open source software. Support options include:

Community Support:

• GitHub Issues and Discussions
• Documentation and examples
• Community-contributed solutions

Professional Services:

• Custom integrations and extensions
• Training and consulting services
• Priority support agreements

Contact the maintainers for professional service inquiries.

Tip

Can’t find the answer you’re looking for? Check our Troubleshooting Guide or create an issue on GitHub with your specific question.

---

Still have questions? Browse our complete documentation or join the community discussions for additional support and insights.