Quick Start Guide

Quick Start Guide

Get your MCP Client Tester environment running in just a few minutes using Docker Compose. This guide will walk you through the essential setup and your first testing session.

Prerequisites

Before you begin, ensure you have:

• Docker (version 20.10 or later)
• Docker Compose (version 2.0 or later)
• Git for cloning the repository
• A domain or localhost setup for testing

Tip

For development, we recommend using a local domain like mcp-tester.local with proper DNS setup or hosts file configuration.

Installation

1. Clone the Repository

   git clone https://github.com/your-org/mcp-client-test.git
   cd mcp-client-test

2. Configure Environment

   Copy the example environment file and customize it:

   cp .env.example .env

   Edit .env with your preferred domain:

   # Project Configuration
   COMPOSE_PROJECT_NAME=mcp-client-tester
   DOMAIN=mcp-tester.local  # Change to your domain
   
   # Server Configuration
   MCP_SERVER_NAME=MCP Client Tester
   MCP_LOG_LEVEL=DEBUG
   
   # Frontend
   PUBLIC_DOMAIN=mcp-tester.local
   PUBLIC_API_URL=https://api.mcp-tester.local

3. Set up Caddy Network

   Create the external Caddy network if it doesn’t exist:

   docker network create caddy 2>/dev/null || true

4. Start the Services

   Launch all services using Docker Compose:

   docker compose up -d

   This starts:

   • Backend: FastAPI server with MCP implementation
   • Frontend: Web interface for monitoring
   • Docs: This documentation site
   • Database: PostgreSQL for session storage
   • Worker: Background task processing

5. Verify Installation

   Check that all services are running:

   docker compose ps

   You should see all services in “Up” status.

First Test Session

Now let’s run your first MCP testing session to verify everything is working correctly.

1. Access the Web Interface

   Open your browser and navigate to:

   • Main App: https://mcp-tester.local (or your configured domain)
   • Documentation: https://docs.mcp-tester.local
   • API: https://api.mcp-tester.local/docs

2. Start a Test Session

   In the web interface:

   • Click “New Session”
   • Select “STDIO Transport” for your first test
   • Configure connection parameters
   • Click “Start Session”

3. Connect with a Test Client

   Use our built-in test client or connect with your own MCP client:

   # Using the built-in test client
   docker compose exec backend python -m app.clients.test_client \
     --transport stdio \
     --session-id your-session-id

4. Monitor the Session

   In the web interface, you should see:

   • Real-time protocol messages
   • Client detection information
   • Session statistics
   • Tool and resource interactions

Understanding the Interface

The MCP Client Tester web interface provides several key areas:

Dashboard Overview

• Active Sessions: Current client connections and their status
• Protocol Statistics: Message counts, error rates, performance metrics
• Client Registry: Detected clients and their capabilities
• Recent Activity: Latest protocol interactions

Session Details

• Protocol Log: Complete request/response history with timestamps
• Client Information: Detected client type, version, capabilities
• Performance Metrics: Connection timing, message throughput
• Tool Usage: Invoked tools and their parameters/results

Monitoring Tools

• Live Updates: Real-time WebSocket updates of protocol activity
• Filtering: Filter messages by type, tool, or time range
• Export: Download session data for offline analysis
• Alerts: Notifications for errors or unusual activity

Testing Different Transports

MCP Client Tester supports all major MCP transport protocols:

STDIO Transport

# Connect via STDIO (recommended for development)
your-mcp-client --transport stdio --server "docker compose exec backend python -m app.mcp.server"

HTTP Transport

# Connect via HTTP
your-mcp-client --transport http --endpoint "https://api.mcp-tester.local/mcp"

Server-Sent Events (SSE)

# Connect via SSE
your-mcp-client --transport sse --endpoint "https://api.mcp-tester.local/mcp/sse"

HTTP Streaming

# Connect via HTTP streaming
your-mcp-client --transport http-streaming --endpoint "https://api.mcp-tester.local/mcp/stream"

Note

Different transports may behave differently with various clients. The tester helps you identify these differences and ensure compatibility.

Common Test Scenarios

Here are some common scenarios to test with your MCP implementation:

Basic Protocol Features

1. Connection Handshake: Verify proper initialization sequence
2. Tool Discovery: Test tools/list and tools/call functionality
3. Resource Access: Test resources/list and resources/read
4. Prompt Templates: Test prompts/list and prompts/get

Advanced Features

1. Progress Reporting: Test long-running operations with progress updates
2. Cancellation: Test operation cancellation and cleanup
3. Sampling: Test server-initiated LLM sampling requests
4. Elicitation: Test server-initiated user input requests

Error Conditions

1. Invalid Requests: Send malformed protocol messages
2. Missing Tools: Call non-existent tools
3. Permission Errors: Test access control and authorization
4. Network Issues: Test connection failure and recovery

Next Steps

Now that you have MCP Client Tester running:

Learn the Interface

Explore the web interface features and monitoring capabilities.

Web Interface Guide →

Understand MCP Protocol

Deep dive into MCP protocol details and message types.

Protocol Overview →

API Integration

Integrate with the REST API for programmatic testing.

API Reference →

Testing Strategies

Learn best practices for comprehensive MCP testing.

Testing Guide →

Troubleshooting

If you encounter issues during setup:

• Services not starting: Check docker compose logs for error messages
• Domain not resolving: Verify your DNS/hosts file configuration
• Permission errors: Ensure Docker has proper permissions
• Port conflicts: Check if ports 80/443 are available for Caddy

For detailed troubleshooting, see our Troubleshooting Guide.

---

Congratulations! You now have a fully functional MCP Client Tester environment. Start exploring the interface and testing your MCP implementations.