Skip to main content
Glama
MCP Test Server

MCP Test Server

by agentspan-ai
IMPORTANT

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-testkit

Or 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 8080

Transports

Transport

Command

Endpoints

stdio

mcp-testkit

MCP JSON-RPC over stdin/stdout

HTTP

mcp-testkit --transport http

MCP at /mcp + REST at /api/* + OpenAPI at /api-docs

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_secret

Tools (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

math_add

a, b

Add two numbers

math_subtract

a, b

Subtract b from a

math_multiply

a, b

Multiply two numbers

math_divide

a, b

Divide (errors on zero)

math_modulo

a, b

Remainder (errors on zero)

math_power

base, exponent

Exponentiation

math_factorial

n

n! (errors on negative)

math_fibonacci

n

Nth Fibonacci number (0-indexed)

String (8 tools)

Tool

Params

Description

string_reverse

text

Reverse a string

string_uppercase

text

Convert to uppercase

string_lowercase

text

Convert to lowercase

string_length

text

Character count

string_char_count

text, char

Count occurrences

string_replace

text, old, new

Replace all occurrences

string_split

text, delimiter

Split by delimiter

string_join

items, delimiter

Join list with delimiter

Collection (8 tools)

Tool

Params

Description

collection_sort

items, reverse?

Sort a list

collection_flatten

items

Recursively flatten nested lists

collection_merge

dict_a, dict_b

Merge dicts (b wins on conflict)

collection_filter_gt

items, threshold

Filter numbers > threshold

collection_unique

items

Remove duplicates (order preserved)

collection_group_by

items, key

Group objects by key

collection_zip

list_a, list_b

Zip into list of pairs

collection_chunk

items, size

Split into chunks

Encoding (8 tools)

Tool

Params

Description

encoding_base64_encode

text

Base64 encode

encoding_base64_decode

data

Base64 decode

encoding_url_encode

text

URL-encode

encoding_url_decode

text

URL-decode

encoding_hex_encode

text

Hex encode

encoding_hex_decode

data

Hex decode

encoding_md5

text

MD5 hash

encoding_sha256

text

SHA-256 hash

DateTime (8 tools)

All operate on provided dates — never use current time.

Tool

Params

Description

datetime_parse

date_string

Parse ISO date to components

datetime_format

year, month, day, format

Format date to string

datetime_add_days

date_string, days

Add/subtract days

datetime_diff

date_a, date_b

Days between two dates

datetime_day_of_week

date_string

Weekday name

datetime_is_leap_year

year

Leap year check

datetime_days_in_month

year, month

Days in month

datetime_week_number

date_string

ISO week number

Validation (8 tools)

All return {valid: bool, reason: string}.

Tool

Params

Description

validation_is_email

text

Email format check

validation_is_url

text

URL format check

validation_is_ipv4

text

IPv4 address check

validation_is_ipv6

text

IPv6 address check

validation_is_uuid

text

UUID format check

validation_is_json

text

Valid JSON check

validation_is_palindrome

text

Palindrome check

validation_matches_regex

text, pattern

Regex match check

Conversion (8 tools)

Tool

Params

Description

conversion_celsius_to_fahrenheit

value

C to F

conversion_fahrenheit_to_celsius

value

F to C

conversion_km_to_miles

value

km to miles

conversion_miles_to_km

value

miles to km

conversion_bytes_to_human

bytes

Bytes to human string

conversion_rgb_to_hex

r, g, b

RGB to hex color

conversion_hex_to_rgb

hex_color

Hex to RGB

conversion_decimal_to_binary

value

Decimal to binary string

Echo / Protocol Testing (8 tools)

Tool

Params

Description

echo

message

Echo input unchanged

echo_error

message

Always raises ToolError

echo_large

size_kb

Deterministic ~N KB text

echo_nested

depth

Nested JSON to depth N

echo_types

—

All JSON types

echo_empty

—

Empty string

echo_multiple

messages

Multiple TextContent blocks

echo_schema

str_param, int_param, float_param, bool_param, list_param, obj_param

Complex schema test

Standalone

Tool

Params

Description

get_weather

city

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/ -v

389 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.py

Available Tools

65 tools
collection_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

    B3.2/5.0

    Scored across 65 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count1/5

    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.

    Completeness3/5

    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

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A 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
    • F
      license
      B
      quality
      D
      maintenance
      An 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
      -