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 .

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

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)

String (8 tools)

Collection (8 tools)

Encoding (8 tools)

DateTime (8 tools)

All operate on provided dates — never use current time.

Validation (8 tools)

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

Conversion (8 tools)

Echo / Protocol Testing (8 tools)

Standalone

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