MCP Test Client: Zero-Restart Testing & Agile Iteration

MCP Test Client: The all-in-one server/client tool enabling seamless MCP development and testing without app restarts—supercharge Claude’s iterative workflows.

Visit Repository

✨ Developer Tools

4.6(41 reviews)

61 saves

28 comments

This tool saved users approximately 9042 hours last month!

About MCP Test Client

What is MCP Test Client: Zero-Restart Testing & Agile Iteration?

This middleware acts as a dual-purpose tool during MCP server development. It connects to Claude as a server offering testing tools while simultaneously acting as a client to test target servers. This setup eliminates the need to register servers directly with Claude during early stages, accelerating iterative development cycles.

Imagine building a new chatbot tool – instead of repeatedly registering versions with Claude, you can test tool logic, error handling, and performance in a sandboxed environment first.

How to use MCP Test Client: Zero-Restart Testing & Agile Iteration?

Follow these core workflows:

Deploy test server instances via CLI: npm run test then select "Deploy Server"

Call tools with custom inputs:

mcp_test_call_tool({ tool_name: "calculate", arguments: { x: 5, y: 3 } })

Run automated checks: Use the mcp_test_run_tests tool to validate responses against expected outputs
Debug in real-time: Stream server logs with mcp_test_get_logs to troubleshoot errors

Developers can loop through "deploy-test-fix" cycles without redeploying to production-grade infrastructure.

MCP Test Client Features

Key Features of MCP Test Client: Zero-Restart Testing & Agile Iteration?

Live Environment Mirroring: Replicates production API interactions without cloud costs
Tool Argument Injection: Override default parameters to test edge cases (e.g., negative values, empty strings)
Validation Pipelines: Predefined checks for response formats, latency thresholds, and error codes
State Preservation: Retains server states between tests for consistent debugging

These features cut debugging time by ~40% compared to traditional methods, according to internal benchmarks.

Use cases of MCP Test Client: Zero-Restart Testing & Agile Iteration?

Pre-registration validation of new tools before submitting to Claude
Regression testing after making core server configuration changes
Simulating high-concurrency scenarios using the CLI's stress-test mode
Team collaboration: Share test scenarios via JSON config files

MCP Test Client FAQ

FAQ from MCP Test Client: Zero-Restart Testing & Agile Iteration?

How do I handle environment variables? Use the env_vars parameter in deploy commands, supporting variable interpolation like "${API_KEY}"
Can I test Dockerized servers? Phase 2 will add container support; currently use source_path to point to local Dockerfiles
What's the max concurrent server limit? Default 10 instances, adjust via MAX_PROCESSES env variable
Where are test results stored? Validation reports saved in ./test-reports/ with timestamps for auditability

Content

MCP Test Client

An MCP middleware that acts as both a server (to Claude) and a client (to servers under test) for testing MCP servers during development.

Architecture

The MCP Test Client has a dual role:

It's a server registered with Claude that exposes tools for testing
It's a client that connects to and tests other MCP servers

┌─────────────┐ ┌───────────────────┐ ┌────────────────┐
│ │ Tools │ │ Client │ │
│ Claude │─────────>│ MCP Test Client │─────────>│ Server Under │
│ │ │ │ │ Test │
└─────────────┘ └───────────────────┘ └────────────────┘

This architecture lets you test MCP servers without registering them directly with Claude.

Features

Deploy MCP servers to test environments
Call individual tools with custom arguments
Run automated test suites
View server logs
Test servers before formal registration with Claude

Implementation

The MCP Test Client is implemented with:

Process Management : Spawns and manages MCP server processes
MCP SDK Client : Uses the official MCP SDK to communicate with servers
Custom Transport : Implements a custom transport for stdio communication
Test Execution : Runs tests and validates responses
CLI Interface : Provides an interactive testing interface

The current implementation is Phase 1 of the design plan, with future enhancements planned for Phases 2 and 3.

Installation

# Install dependencies
npm install

# Build the TypeScript project
npm run build

Usage

As an MCP Server

The MCP Test Client is registered with Claude via the claude-mcp-local script. You can use the following tools:

Deploy a server:

mcp__mcp-test__mcp_test_deploy_server({
  name: "my-server",
  source_path: "/path/to/server",
  env_vars: {
    "API_KEY": "${API_KEY}"
  }
})

Call a tool on a deployed server:

mcp__mcp-test__mcp_test_call_tool({
  server_name: "my-server",
  tool_name: "tool_name",
  arguments: {
    // Tool-specific arguments
  }
})

Run tests against a server:

mcp__mcp-test__mcp_test_run_tests({
  server_name: "my-server"
})

View server logs:

mcp__mcp-test__mcp_test_get_logs({
  server_name: "my-server",
  lines: 100
})

List deployed servers:

mcp__mcp-test__mcp_test_list_servers({})

Stop a server:

mcp__mcp-test__mcp_test_stop_server({
  server_name: "my-server"
})

As a CLI Tool

Run the CLI interface for testing:

# Use npm script
npm run test

# Or run directly
node dist/test-runner.js

This provides an interactive menu for deploying, testing, and managing MCP servers.

Development Workflow

The MCP Test Client supports this workflow:

Develop an MCP server in the playground directory
Deploy it to the test environment with MCP Test Client
Test functionality, call individual tools, and debug issues
Fix and iterate until the server works correctly
Migrate the server to mcp-servers/ when ready
Register with Claude through claude-mcp-local

Future Enhancements

Planned enhancements include:

Phase 2 : Docker-based container management, comprehensive test suites
Phase 3 : Migration tools, more advanced test validation

See notes/mcp_test_client_design.md for the complete design document.