# MCP Server Contract Tester — stdio + WebSocket Transports, JSON Schema 2020-12 Tool Validation

End-to-end Model Context Protocol contract testing: JSON-RPC 2.0 initialize handshake and version negotiation over stdio (newline-delimited) and WebSocket (one message per text frame), tools/list inputSchema object-root and draft 2020-12 compilation, resources/list + read, prompts/list + get, ping, -32601 error semantics, sampling/createMessage round-trip, and framing discipline — with an embedded reference server for offline self-verification.

> Canonical page: https://elysiatools.com/en/tools/model-context-protocol-mcp-server-tool-schema-stdio-websocket-transport-contract-tester

- **Category:** AI Tools

- **Keywords:** mcp, model context protocol, contract test, json-rpc 2.0, stdio transport, websocket transport, tools list, input schema, json schema 2020-12, capability negotiation, sampling, server compliance

## Overview

Protocol basis (initialize era, 2024-11-05 … 2025-11-25): the initialize request carries protocolVersion, client capabilities and clientInfo; the server answers serverInfo + capabilities; the client must then send notifications/initialized. The official stdio binding is newline-delimited JSON-RPC — no embedded newlines, logs on stderr, stdout reserved for MCP messages; WebSocket is a custom binding (spec § Custom Transports) carrying one JSON-RPC message per text frame. Every tool's inputSchema must be a JSON Schema with type:object at the root; this tester compiles each one under Ajv draft 2020-12. sampling is a server→client request: when the client declares the sampling capability, a server may send sampling/createMessage (messages[] + maxTokens), which the tester answers per spec and validates. The 2026-07-28 revision moves to a stateless core where servers no longer initiate requests; this tester targets the classic initialize era and notes that in the report. The default mode self-verifies the embedded, fully compliant reference server over an in-process stdio stream pair and a real loopback TCP WebSocket — deterministic and offline. For live targets, pick stdio-command (spawns your command) or websocket-url (connects to ws:// or wss://); connection failures become failed handshake checks on the report card rather than tool errors.

## Inputs

- **Test mode** (select)
- **Server command (stdio mode)** (text): npx -y @modelcontextprotocol/server-everything
- **WebSocket URL (ws:// or wss://)** (text): ws://127.0.0.1:3001/mcp
- **Protocol version to request** (select)
- **Request timeout (ms)** (number): 5000
- **Validate tool input schemas (JSON Schema 2020-12)** (checkbox)

## When to use

- Developing a custom MCP server and needing to verify JSON-RPC 2.0 framing and capability negotiation before deployment.
- Validating that tool input schemas compile cleanly under JSON Schema draft 2020-12 with root object constraints.
- Auditing MCP server endpoints over stdio subprocesses or WebSocket URLs for protocol compliance and proper error handling.

## How it works

- Select the test execution mode: offline reference self-test, an external stdio command subprocess, or a remote WebSocket URL.
- Configure protocol parameters, including the target protocol version (e.g., 2025-06-18), request timeout thresholds, and schema validation toggles.
- The tester establishes the transport connection, executes the initialize handshake, and validates responses for tools, resources, prompts, ping, and sampling.
- Review an interactive HTML compliance report card featuring transport score donuts, Ajv schema compilation logs, and detailed pass/fail check breakdowns.

## Use cases

- Automating MCP specification compliance checks in CI/CD pipelines for stdio-based CLI tools.
- Debugging WebSocket-based MCP agent servers to ensure correct message framing and capability exchanges.
- Verifying multi-tool LLM integrations to catch invalid JSON Schema structures before client runtime failures.

## Frequently asked questions

### What transports are supported by the contract tester?

It supports newline-delimited JSON-RPC over stdio subprocesses and single-message text frame JSON-RPC over WebSocket (ws:// and wss://) connections.

### How are tool input schemas validated?

Each tool schema is validated for a root type of 'object' and compiled against the JSON Schema draft 2020-12 specification using Ajv.

### What happens during the reference self-test mode?

It runs an embedded, fully compliant reference server over an in-process stdio stream pair and a loopback TCP WebSocket to verify all protocol checks offline.

### Does the tester verify server-initiated sampling?

Yes, when sampling capabilities are declared, it tests and validates the round-trip response for sampling/createMessage requests.

### How are unknown methods and error handling evaluated?

The tester issues undefined RPC calls to confirm the server properly returns standard JSON-RPC -32601 Method Not Found error structures.

## Related tools

- [CSV to Database Migration Planner](https://elysiatools.com/en/tools/csv-to-database-migration-planner): Infer a relational schema from CSV data and generate create-table plus ALTER migration plans for PostgreSQL, MySQL, SQLite, or SQL Server
- [ECharts Theme Token Extractor](https://elysiatools.com/en/tools/echarts-theme-token-extractor): Extract design tokens — colors, numbers, font sizes and strings — from an ECharts theme JSON and export them straight into your design system. Paste a theme object (the kind registered via echarts.init(dom, themeName)) and the tool walks every leaf, tagging each color (with optional named/rgb → hex normalization), spacing number, font size and string, then emits clean CSS variables, a Tailwind theme.extend config, Style Dictionary tokens.json, or SCSS variables. Bridges the gap between an ECharts visualization theme and Figma/CSS/Tailwind design tokens without copying each value by hand.
- [Image Palette to Design Tokens](https://elysiatools.com/en/tools/image-to-design-tokens): Extract a dominant color palette from an image (k-means clustering), then export it as CSS variables, SCSS variables, a Tailwind config, or JSON design tokens — with named colors and an auto-generated shade scale for each
- [JWK Generator & Parser](https://elysiatools.com/en/tools/jwk-generator): Generate JSON Web Keys (JWK) for RSA, EC (P-256/P-384/P-521/secp256k1), and OKP (Ed25519/Ed448/X25519/X448), or parse an existing JWK to inspect its parameters, thumbprint, and metadata
- [OCR PDF to Structured JSON Bridge](https://elysiatools.com/en/tools/ocr-pdf-to-structured-json-bridge): Extract the PDF text layer with geometry (lines by y-position, tables by column gaps, headings by font size, colon key-value pairs), then fill a user-supplied JSON Schema field by field — labels matched by normalized keys, values coerced to declared types and validated with ajv.
- [JSON Key Extractor](https://elysiatools.com/en/tools/json-key-extractor): Extract all keys from JSON objects with multiple output formats. Perfect for analyzing JSON structure, documentation generation, and understanding complex nested objects.
- [JSON-LD Generator from CSV](https://elysiatools.com/en/tools/json-ld-generator-from-csv): Turn CSV or Excel rows into Schema.org JSON-LD for articles, products, or events, with validation-ready output for SEO workflows
- [LLM Tool-Calling JSON Schema Builder](https://elysiatools.com/en/tools/llm-tool-calling-json-schema-builder): Define an LLM tool once and emit validated function-calling payloads for OpenAI, Anthropic and Gemini.

## Samples

- [Chat Transcript JSON Samples](https://elysiatools.com/en/samples/chat-transcript-json): JSON examples for multi-role chat transcripts
- [Rich Media JSON Samples](https://elysiatools.com/en/samples/rich-media-json): JSON examples for popular rich text editors (TipTap, Quill, Slate)
- [Terraform Plan JSON Samples](https://elysiatools.com/en/samples/terraform-plan-json-samples): Sample Terraform plan JSON files exported from terraform show -json style payloads for dependency visualization and change review
- [JSON Samples](https://elysiatools.com/en/samples/json): JSON (JavaScript Object Notation) format examples from simple to complex structures