MCP Test Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@MCP Test Server Add 10 and 20"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Final release. Maintained releases of mcp-testkit ended with the Agentspan → Orkes Conductor merge (August 17, 2026). This repository is archived read-only; pip install mcp-testkit keeps working and the server remains a usable generic MCP test harness as-is.
MCP Test Server
A Python MCP server with 65 deterministic tools across 8 groups, supporting stdio, HTTP, and REST API transports. Built for consistent, repeatable MCP protocol testing.
Install
pip install mcp-testkitOr from source:
git clone https://github.com/agentspan-ai/mcp-testkit.git
cd mcp-testkit
pip install -e .Related MCP server: mcp-test-server
Quick Start
# stdio (default)
mcp-testkit
# SSE + REST API on port 3001
mcp-testkit --transport http
# With bearer token authentication
mcp-testkit --transport http --auth super_secret_key
# Custom host/port
mcp-testkit --transport http --host 0.0.0.0 --port 8080Transports
Transport | Command | Endpoints |
stdio |
| MCP JSON-RPC over stdin/stdout |
HTTP |
| MCP at |
Authentication
Pass --auth <key> to require a Bearer token on all requests (both MCP SSE and REST):
mcp-testkit --transport http --auth my_secret
# Clients must include:
# Authorization: Bearer my_secretTools (65 total)
All tools are deterministic — same input always produces same output. No randomness, no current time, no external state.
Math (8 tools)
Tool | Params | Description |
|
| Add two numbers |
|
| Subtract b from a |
|
| Multiply two numbers |
|
| Divide (errors on zero) |
|
| Remainder (errors on zero) |
|
| Exponentiation |
|
| n! (errors on negative) |
|
| Nth Fibonacci number (0-indexed) |
String (8 tools)
Tool | Params | Description |
|
| Reverse a string |
|
| Convert to uppercase |
|
| Convert to lowercase |
|
| Character count |
|
| Count occurrences |
|
| Replace all occurrences |
|
| Split by delimiter |
|
| Join list with delimiter |
Collection (8 tools)
Tool | Params | Description |
|
| Sort a list |
|
| Recursively flatten nested lists |
|
| Merge dicts (b wins on conflict) |
|
| Filter numbers > threshold |
|
| Remove duplicates (order preserved) |
|
| Group objects by key |
|
| Zip into list of pairs |
|
| Split into chunks |
Encoding (8 tools)
Tool | Params | Description |
|
| Base64 encode |
|
| Base64 decode |
|
| URL-encode |
|
| URL-decode |
|
| Hex encode |
|
| Hex decode |
|
| MD5 hash |
|
| SHA-256 hash |
DateTime (8 tools)
All operate on provided dates — never use current time.
Tool | Params | Description |
|
| Parse ISO date to components |
|
| Format date to string |
|
| Add/subtract days |
|
| Days between two dates |
|
| Weekday name |
|
| Leap year check |
|
| Days in month |
|
| ISO week number |
Validation (8 tools)
All return {valid: bool, reason: string}.
Tool | Params | Description |
|
| Email format check |
|
| URL format check |
|
| IPv4 address check |
|
| IPv6 address check |
|
| UUID format check |
|
| Valid JSON check |
|
| Palindrome check |
|
| Regex match check |
Conversion (8 tools)
Tool | Params | Description |
|
| C to F |
|
| F to C |
|
| km to miles |
|
| miles to km |
|
| Bytes to human string |
|
| RGB to hex color |
|
| Hex to RGB |
|
| Decimal to binary string |
Echo / Protocol Testing (8 tools)
Tool | Params | Description |
|
| Echo input unchanged |
|
| Always raises ToolError |
|
| Deterministic ~N KB text |
|
| Nested JSON to depth N |
| — | All JSON types |
| — | Empty string |
|
| Multiple TextContent blocks |
|
| Complex schema test |
Standalone
Tool | Params | Description |
|
| Fixed response: 77°F, sunny, always |
REST API
When running with --transport http, all tools are also available as HTTP endpoints:
# GET endpoints (math, conversion, some echo, weather)
curl "http://localhost:3001/api/math/add?a=3&b=5"
# {"result": 8.0}
curl "http://localhost:3001/api/weather?city=NYC"
# {"city":"NYC","temperature_f":77,...}
# POST endpoints (string, collection, encoding, datetime, validation, some echo)
curl -X POST "http://localhost:3001/api/string/reverse" \
-H "Content-Type: application/json" \
-d '{"text":"hello"}'
# {"result": "olleh"}
curl -X POST "http://localhost:3001/api/encoding/sha256" \
-H "Content-Type: application/json" \
-d '{"text":"hello"}'
# {"result": "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824"}OpenAPI spec at GET /api-docs (OpenAPI 3.0.3).
With auth enabled, include Authorization: Bearer <key> on all requests.
Testing
python3 -m pytest tests/ -v389 tests covering all tools, REST API endpoints, auth, OpenAPI spec, and integration.
Project Structure
mcp-testkit/
├── pyproject.toml # Package config, deps, CLI entry point
├── mcp_test_server/
│ ├── __init__.py # Package version
│ ├── server.py # Entry point — MCP server + REST API + auth
│ ├── api.py # REST API routes + OpenAPI spec generation
│ └── tools/
│ ├── __init__.py # Tool group registry
│ ├── math_tools.py
│ ├── string_tools.py
│ ├── collection_tools.py
│ ├── encoding_tools.py
│ ├── datetime_tools.py
│ ├── validation_tools.py
│ ├── conversion_tools.py
│ └── echo_tools.py # Includes get_weather
└── tests/
├── test_math_tools.py
├── test_string_tools.py
├── test_collection_tools.py
├── test_encoding_tools.py
├── test_datetime_tools.py
├── test_validation_tools.py
├── test_conversion_tools.py
├── test_echo_tools.py
├── test_api.py
└── test_integration.pyAvailable Tools
65 toolscollection_chunkC
Split a list into chunks of a given size.
Args: items: The list to split. size: The chunk size.
Inputs: size (required), items (required). Returns: result
collection_filter_gtC
Filter numbers greater than a threshold.
Args: items: List of numbers to filter. threshold: The threshold value.
Inputs: items (required), threshold (required). Returns: result
collection_flattenC
Recursively flatten nested lists.
Args: items: A potentially nested list to flatten.
Inputs: items (required). Returns: result
collection_group_byC
Group a list of objects by a key.
Args: items: List of dictionaries to group. key: The key to group by.
Inputs: key (required), items (required). Returns: result
collection_mergeB
Merge two dictionaries. Values from dict_b win on conflict.
Args: dict_a: The base dictionary. dict_b: The dictionary to merge in (wins on conflict).
Inputs: dict_a (required), dict_b (required). Returns: result
collection_sortC
Sort a list of items.
Args: items: The list to sort. reverse: If True, sort in descending order.
Inputs: items (required), reverse. Returns: result
collection_uniqueA
Remove duplicates from a list, preserving order.
Uses JSON serialization for dedup keys to handle mixed types.
Args: items: The list to deduplicate.
Inputs: items (required). Returns: result
collection_zipC
Zip two lists into a list of pairs.
Args: list_a: The first list. list_b: The second list.
Inputs: list_a (required), list_b (required). Returns: result
conversion_bytes_to_humanA
Convert a byte count to a human-readable string (e.g., '1.00 KB').
Inputs: bytes (required). Returns: result
conversion_celsius_to_fahrenheitA
Convert a temperature from Celsius to Fahrenheit.
Inputs: value (required). Returns: result
conversion_decimal_to_binaryA
Convert a decimal integer to its binary string representation (without '0b' prefix).
Inputs: value (required). Returns: result
conversion_fahrenheit_to_celsiusA
Convert a temperature from Fahrenheit to Celsius.
Inputs: value (required). Returns: result
conversion_hex_to_rgbA
Convert a hex color string to RGB values. Supports with or without '#' prefix.
Inputs: hex_color (required). Returns: result
conversion_km_to_milesA
Convert a distance from kilometers to miles.
Inputs: value (required). Returns: result
conversion_miles_to_kmA
Convert a distance from miles to kilometers.
Inputs: value (required). Returns: result
conversion_rgb_to_hexA
Convert RGB color values (0-255) to a hex color string.
Inputs: b (required), g (required), r (required). Returns: result
datetime_add_daysB
Add N days to a date and return the resulting ISO date string.
Inputs: days (required), date_string (required). Returns: result
datetime_day_of_weekB
Return the weekday name (e.g., 'Friday') for a given date.
Inputs: date_string (required). Returns: result
datetime_days_in_monthB
Return the number of days in the given month and year.
Inputs: year (required), month (required). Returns: result
datetime_diffB
Return the number of days between two dates (a - b).
Inputs: date_a (required), date_b (required). Returns: result
datetime_formatC
Format a date to a string using a strftime format specifier.
Inputs: day (required), year (required), month (required), format (required). Returns: result
datetime_is_leap_yearB
Return whether the given year is a leap year.
Inputs: year (required). Returns: result
datetime_parseB
Parse an ISO date string and return its components {year, month, day, hour, minute, second}.
Inputs: date_string (required). Returns: result
datetime_week_numberC
Return the ISO week number for the given date.
Inputs: date_string (required). Returns: result
echoA
Return the input message unchanged.
Inputs: message (required). Returns: result
echo_emptyA
Return an empty string result.
Inputs: no named parameters. Returns: result
echo_errorA
Always raises a ToolError with the given message.
Inputs: message (required). Returns: result
echo_largeC
Return deterministic text of approximately N kilobytes.
Inputs: size_kb (required). Returns: result
echo_multipleB
Return multiple TextContent blocks, one per message.
Inputs: messages (required). Returns: result
echo_nestedC
Return nested JSON structure to the given depth.
Inputs: depth (required). Returns: result
echo_schemaC
Echo all parameters back as JSON.
Inputs: int_param (required), obj_param (required), str_param (required), bool_param (required), +2 more. Returns: result
echo_typesC
Return an object containing all JSON types.
Inputs: no named parameters. Returns: result
encoding_base64_decodeA
Base64-decode a string. Returns an error if the input is not valid base64.
Inputs: data (required). Returns: result
encoding_base64_encodeB
Base64-encode a string.
Inputs: text (required). Returns: result
encoding_hex_decodeA
Hex-decode a string. Returns an error if the input is not valid hex.
Inputs: data (required). Returns: result
encoding_hex_encodeC
Hex-encode a string.
Inputs: text (required). Returns: result
encoding_md5B
Return the MD5 hash hex digest of a string.
Inputs: text (required). Returns: result
encoding_sha256B
Return the SHA-256 hash hex digest of a string.
Inputs: text (required). Returns: result
encoding_url_decodeB
URL-decode a percent-encoded string.
Inputs: text (required). Returns: result
encoding_url_encodeB
URL-encode a string using percent-encoding (spaces become +).
Inputs: text (required). Returns: result
get_weatherA
Get weather for a city. Always returns fixed deterministic data (77°F, sunny).
Inputs: city (required). Returns: result
math_addB
Add two numbers and return the sum.
Inputs: a (required), b (required). Returns: result
math_divideA
Divide a by b. Returns an error if b is zero.
Inputs: a (required), b (required). Returns: result
math_factorialA
Return n factorial (n!). Returns an error if n is negative.
Inputs: n (required). Returns: result
math_fibonacciA
Return the nth Fibonacci number (0-indexed). Returns an error if n is negative.
Inputs: n (required). Returns: result
math_moduloA
Return the remainder of a divided by b. Returns an error if b is zero.
Inputs: a (required), b (required). Returns: result
math_multiplyB
Multiply two numbers and return the product.
Inputs: a (required), b (required). Returns: result
math_powerB
Raise base to the power of exponent.
Inputs: base (required), exponent (required). Returns: result
math_subtractA
Subtract b from a and return the difference.
Inputs: a (required), b (required). Returns: result
string_char_countB
Count occurrences of a character in a string.
Inputs: char (required), text (required). Returns: result
string_joinA
Join a list of strings with a delimiter.
Inputs: items (required), delimiter (required). Returns: result
string_lengthB
Return the character count of a string.
Inputs: text (required). Returns: result
string_lowercaseB
Convert a string to lowercase.
Inputs: text (required). Returns: result
string_replaceB
Replace all occurrences of old with new in a string.
Inputs: new (required), old (required), text (required). Returns: result
string_reverseB
Reverse a string.
Inputs: text (required). Returns: result
string_splitC
Split a string by a delimiter.
Inputs: text (required), delimiter (required). Returns: result
string_uppercaseC
Convert a string to uppercase.
Inputs: text (required). Returns: result
validation_is_emailB
Check whether a string is a valid email address format.
Inputs: text (required). Returns: result
validation_is_ipv4B
Check whether a string is a valid IPv4 address.
Inputs: text (required). Returns: result
validation_is_ipv6A
Check whether a string is a valid IPv6 address.
Inputs: text (required). Returns: result
validation_is_jsonC
Check whether a string is valid JSON.
Inputs: text (required). Returns: result
validation_is_palindromeB
Check whether a string is a case-sensitive palindrome.
Inputs: text (required). Returns: result
validation_is_urlA
Check whether a string is a valid URL with http or https scheme.
Inputs: text (required). Returns: result
validation_is_uuidC
Check whether a string is a valid UUID.
Inputs: text (required). Returns: result
validation_matches_regexB
Check whether a string matches a given regular expression pattern.
Inputs: text (required), pattern (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 65 tools
Each tool has a clearly distinct purpose, and the category prefixes make selection unambiguous. Even the many echo_* variants map to discrete test behaviors rather than overlapping functionality.
All tool names use a consistent snake_case pattern with a category prefix (string_, collection_, encoding_, etc.) and a clear action or property. There are no mixed conventions or ambiguous verb styles.
65 tools is far beyond a reasonable scoped set for any server. While a test server may intentionally exercise many capabilities, the sheer volume suggests many tools are redundant test variants rather than each earning a place for a cohesive purpose.
Coverage is broad across utility categories, but notable gaps exist: no string trim/substring, no general collection filter/map, no datetime now/timezone, no math sqrt/trig, etc. For a utility/test grab-bag, agents can work around many gaps but the surface is not complete.
Maintenance
Related MCP Connectors
Self-hosted MCP server: 26 deterministic dev, security, and EVM tools.
MCP compatibility and transport verification server.
MCP compatibility and transport verification server.
MCP compatibility and transport verification server.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA test server implementing all features of the MCP protocol, including prompts, tools, resources, and sampling, designed for testing MCP clients rather than practical applications.MIT
- FlicenseNot gradedqualityDmaintenanceA lightweight MCP test server for verifying client connectivity, providing tools, resources, and prompts for integration.-
- FlicenseBqualityDmaintenanceAn MCP server framework featuring dynamic tool loading and a modular one-tool-per-file architecture for rapid development. It supports both Stdio and HTTP transport modes, offering automated test generation and centralized configuration management.11-
- FlicenseNot gradedqualityDmaintenanceA standardized MCP server designed for testing integration with the Des MCP Server Testing API. It allows AI agents to interact with testing endpoints using tools implemented via the Model Context Protocol.-