MCP Toolkit: Server Mock

Run mock servers from 'mcpdesc' files - MCP Descriptions - generated by the mcpcontract CLI.

You may use 'mcpmock' for:

• Testing: Test MCP clients without a live MCP service
• Development: Build clients against stable mock data
• Demos: Showcase MCP capabilities with controlled, reproducible responses

Features

• ✅ Mock all MCP capabilities (initialize, tools/list, tools/call, prompts/list, prompts/get, resources/list, resources/templates/list, resources/read)
• ✅ Stdio and HTTP transports (streamable-http)
• ✅ Protocol-version agnostic (works with any MCP client version)
• ✅ Automatic data generation from JSON schemas
• ✅ structuredContent in tools/call responses when outputSchema is declared (MCP spec 2025-06-18)
• ✅ Record data from real MCP traffic into JSONL documents and replay
• ✅ Generate data with AI-assistance (requires Copilot CLI)
• ✅ Custom override of existing mock data via JSON files

Quick Start

npm install -g @cisco_open/mcptoolkit-mock

# Verify
mcpmock --help

For development / local builds:

git clone https://github.com/cisco-open/mcptoolkit-mock.git
cd mcptoolkit-mock
npm install && npm run build && npm link

using stdio

mcpmock uses stdio transport by default: JSON-RPC 2.0 messages are sent via stdin, responses come back on stdout. No HTTP port, no curl — the shell is the client.

# One-shot — pipe a single request, get a response, process exits
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get-current","arguments":{"city":"London"}}}' | \
  mcpmock run tests/fixtures/mcpdesc/weather-server.mcpdesc.json

Returns auto-generated weather data from the mock server.

using streamable HTTP

mcpmock start a Persistent HTTP server — stays running, accepts requests from any MCP client

mcpmock run tests/fixtures/mcpdesc/weather-server.mcpdesc.json \
  --transport streamable-http \
  --port 3000 \
  --verbose

In another terminal, we'll invoke an MCP tool using the MCP Inspector CLI for example

npx @modelcontextprotocol/inspector --cli http://localhost:3000 \
  --transport http \
  --method tools/call \
  --tool-name get-current \
  --tool-arg city=London

Returns auto-generated weather data from the mock server.

For a comprehensive walkthrough, see GETTING_STARTED.md.

The MCP Description (mcpdesc) format

An MCP Description (mcpdesc) is a portable, machine-readable contract that declares everything an MCP server offers — tools, resources, prompts, transports, and security — much like OpenAPI does for REST APIs.

Every mcpmock command takes an mcpdesc file as input. To generate one from a live MCP server, use mcpcontract dump:

mcpcontract dump \
  --transport streamable-http \
  --url "https://your-mcp-server/mcp" \
  --output server.mcpdesc.json

Canonical source: the MCP Description specification, versioned schemas, and full governance live in the mcptoolkit-contract repository (spec/ and schemas/mcp-description/). mcpmock vendors schema v0.7.0 from that source.

Mock Data: Two Primary Workflows

1. Build Workflow

Generate realistic mock data with AI assistance, then run the mock server. Best when starting a new project or when you don't have access to a real server.

# Step 1: Generate mock data files
mcpmock build \
  --mcpdesc weather-server.mcpdesc.json \
  --output mocks/

# Step 2: Run server with generated mocks
mcpmock run \
  weather-server.mcpdesc.json \
  --data mocks/ \
  --transport streamable-http \
  --port 3000

👉 Tutorial: Building Mocks with AI

2. Record Workflow

Capture real traffic from a live server, then replay it. Best for regression testing or when you need exact real-world responses.

# Step 1: Record traffic (proxy mode)
mcpmock record \
  --mcpdesc weather-server.mcpdesc.json \
  --port 3000 \
  --upstream http://real-server:8080 \
  --output traffic.jsonl

# Step 2: Replay recorded traffic
mcpmock run \
  weather-server.mcpdesc.json \
  --replay traffic.jsonl \
  --port 3000

👉 Tutorial: Recording Traffic 👉 Authoring Replay Datasets (design-first)

Commands

mcpmock build - Generate Mock Data Files

mcpmock build --mcpdesc weather-server.mcpdesc.json --output mock-data/
mcpmock build --mcpdesc api-inventory.mcpdesc.json --output mock-data/ --no-ai

Options:

• --mcpdesc <file> (required) - Path to mcpdesc file from mcpcontract
• --output <dir> (required) - Output directory for mock data files
• --no-ai - Skip AI generation, use faker only
• --verbose - Enable detailed logging

Uses a three-tier approach (Copilot CLI → runSubagent → Faker fallback) and detects shared parameters across tools for consistency. Generates one <tool-name>.json per tool, ready for use with mcpmock run --data.

Note: Currently generates mock data for tools only. Prompts and resources support coming in a future release.

mcpmock record - Record Traffic

mcpmock record \
  --mcpdesc server.mcpdesc.json \
  --port 3000 \
  --upstream http://real-server:8080 \
  --output traffic.jsonl

Options:

• --mcpdesc <file> (required) - Path to mcpdesc file
• --upstream <url> (required) - URL of the real MCP server to proxy to
• --output <file> (required) - Output JSONL file for recorded traffic
• --port <number> - Port for the proxy to listen on (default: 3000)
• --verbose - Enable detailed logging

Note: Only HTTP transport is supported for recording. For stdio-based servers, use the mcptest integration workflow (mcpmock import) or the build workflow instead.

mcpmock import - Convert mcptest Logs

Convert mcptest execution logs to JSONL for replay:

mcpmock import --execution-log execution.json --output traffic.jsonl
mcpmock run server.mcpdesc.json --replay traffic.jsonl

👉 Tutorial: mcptest Integration

mcpmock run - Start Mock Server

# Auto-generated data
mcpmock run api-inventory.mcpdesc.json

# With custom mock data
mcpmock run weather-server.mcpdesc.json --data examples/weather/

# HTTP transport
mcpmock run weather-server.mcpdesc.json --transport streamable-http --port 3000

# Replay recorded traffic
mcpmock run weather-server.mcpdesc.json --replay traffic.jsonl --port 3000

Options:

• <mcpdesc> (required, positional) - Path to mcpdesc file from mcpcontract
• --data <dir> - Directory containing custom mock data JSON files
• --transport <type> - stdio (default) or streamable-http
• --port <number> - Port for HTTP transport (default: 3000)
• --replay <file> - Replay recorded traffic from JSONL file
• --similarity-threshold <percent> - Minimum similarity for replay matches (1-100, default: 70)
• --debug - Enable debug mode with detailed matching analysis
• --verbose - Enable detailed logging to stderr

Custom mock data: Place JSON files named after each tool (e.g., get-forecast.json → get-forecast tool) in the --data directory. Auto-generated data is used when no override exists.

structuredContent: When a tool declares an outputSchema, the response includes both a backward-compatible content text block and a structuredContent object conforming to that schema. Faker generation uses the outputSchema shape when present.

Replay matching: Exact matches (100%) and similar matches (≥threshold) return the recorded response; below-threshold falls back to auto-generated data. For resources/read, replay matching is URI-aware (resources/read:<uri>), so different resource URIs can return distinct recorded content, and recorded error responses are replayed as errors. Tune strictness with --similarity-threshold.

Testing HTTP transport with MCP Inspector CLI:

npx @modelcontextprotocol/inspector --cli http://localhost:3000 \
  --transport http \
  --method tools/list

mcpmock completion - Shell Completion

eval "$(mcpmock completion bash)"   # Bash — add to ~/.bashrc for persistence
eval "$(mcpmock completion zsh)"    # Zsh  — add to ~/.zshrc for persistence
mcpmock completion fish > ~/.config/fish/completions/mcpmock.fish

mcpmock agents - AI Assistant Reference

mcpmock agents                    # Overview
mcpmock agents --command run      # Command-specific help (~500 tokens)
mcpmock agents --workflows        # All workflows
mcpmock agents --all              # Complete reference

Examples

Weather Server (tests/fixtures/mcpdesc/weather-server.mcpdesc.json)

Simple 2-tool server (tools: get-current, get-forecast):

mcpmock run tests/fixtures/mcpdesc/weather-server.mcpdesc.json --verbose
mcpmock run tests/fixtures/mcpdesc/weather-server.mcpdesc.json --data examples/weather/ --verbose

Custom data for London is available in examples/weather/.

API Inventory Server (tests/fixtures/mcpdesc/api-inventory.mcpdesc.json)

Real-world 5-tool example (tools: list-organizations, search, stats, refresh-cache, schema-version):

mcpmock run tests/fixtures/mcpdesc/api-inventory.mcpdesc.json --verbose

Troubleshooting

Server won't start

# Verify mcpdesc file is valid
mcpcontract validate --mcpdesc api-inventory.mcpdesc.json

Custom mock data not loading

# Enable verbose logging — filenames (without .json) must match tool names exactly
mcpmock run server.mcpdesc.json --data mock-data/ --verbose

Client connection issues

Stdio:

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | \
  mcpmock run server.mcpdesc.json

HTTP:

mcpmock run server.mcpdesc.json --port 3000 --verbose
npx @modelcontextprotocol/inspector --cli http://localhost:3000 --transport http --method tools/list

Development

npm install           # Install dependencies
npm run build         # Build TypeScript
npm run watch         # Watch mode
npm test              # Run tests
npm run test:watch    # Watch mode for tests
npm run test:coverage # Coverage report

VS Code Extension (⚠️ Experimental)

For UI-based mock generation, there's an experimental VS Code extension. See Tutorial: VS Code Extension for setup. The CLI workflows are recommended for production use.

License

This software is licensed under the Apache License 2.0. See LICENSE for details.