mcp-test

The MCP Test Server is a lightweight, purpose-built server that implements the Model Context Protocol (MCP) to help clients exercise various edge cases. It exposes tools designed for testing error handling, timeouts, dynamic tool management, and content rendering (including images). You can run the server either via a Rust execution path (compiled from source or installed) and then interact with the defined tools over the configured transport. The included tools let you deliberately fail, delay responses, verify successful responses, return a logo image in multiple formats, and dynamically add or remove tools at runtime. This makes it a practical sandbox for validating client behavior under a range of MCP scenarios.

To use the server, start it with your preferred transport (stdio or HTTP) and then invoke the provided tools through the MCP RPC interface. The tool set includes: fail (always errors), delay (sleeps for a given duration), succeed (instant success), get_image (returns an MCP logo in a chosen image format), add_tool/remove_tool (dynamic session modifications), and log_message (emit log notifications over RPC). The server adheres to the MCP spec and leverages the Rust SDK for implementation, ensuring realistic MCP interactions for client testing.

Prerequisites:

• Rust toolchain (Rustup, cargo) installed on your system.
• Internet access to fetch dependencies.

Install from GitHub (buildable from source):

# Option 1: Build from source
git clone https://github.com/dastrobu/mcp-test-server
cd mcp-test-server
cargo build --release

# Run the server (using the built binary in target/release)
./target/release/mcp-test-server --transport stdio

Install via cargo install (Rust package install from Git repository):

cargo install --git https://github.com/dastrobu/mcp-test-server

# Run the installed binary
mcp-test-server --transport stdio

Note: The server supports stdio by default and HTTP (Streamable HTTP) as an alternative transport. If you prefer HTTP, run with:

mcp-test-server --transport http --port 3000

Tips and considerations:

• The server offers dynamic tool management: add_tool and remove_tool let you modify the session tools at runtime, which is useful for testing client resilience to changes in available operations.
• get_image supports multiple image formats (png, gif, jpeg, webp, avif). When testing clients, try varying type and optional audience/priority annotations to validate metadata handling.
• log_message sends MCP logging notifications over RPC; ensure clients subscribe to logs if you want to observe runtime diagnostics.
• If you encounter issues with HTTP transport, check that the port is not blocked by a firewall and that the Streamable HTTP endpoint is correctly configured. When using stdio, the server communicates over standard input/output pipes.
• For dynamic tool definitions, you can provide a JSON schema for input to add_tool to validate client-provided data.
• Environment variables are not strictly required for normal operation, but you can expose extra debugging or tracing options via standard Rust logging facilities if needed.