Skip to content

Documentation

mcp-test

A Model Context Protocol server built as a fixture for testing MCP gateways. Twelve deterministic tools, three auth methods, a Postgres- backed audit log of every call, and an embedded portal for live inspection.

Quickstart GitHub
Portal preview

Inspect every call from the browser

Click any frame to open it full-size. Use the side rails or the arrow keys to step through.

Portal

Dashboard

Live counts, error rate, p50/p95 latency, and the most recent calls across every tool.

Portal

Audit log

Every call, filterable by tool, user, status, and source. Sanitized parameters and full response shape are one click away.

Portal

Inspection drawer

Click any row for the four-tab side panel: Overview / Request / Response / Notifications. Replay and Compare are inline; the URL deep-links to the open event so a drawer state is shareable.

Portal

Side-by-side compare

Stash any two events and the comparison page renders a JSON-path-aware structural diff. Walks objects and arrays by key/index, so reordered keys don't masquerade as changes.

Portal

Live tail

SSE stream of new audit events as they're written, surfaced in a fixed-cap buffer above the historical filter view. The table itself stays still so the live read doesn't blow away your filtered context.

Portal

JSONB filters

Server-side path filters compile to JSONB containment against the existing GIN indexes: param.=v, response.=v, header.=v, has=. Type-detected values; quote to force string.

Portal

Tools

Twelve test fixtures grouped by category. Pick one to see its schema, run it, or browse the audit rows it produced.

Portal

Try it

Per-tool form generated from the JSON schema. Sliders, dropdowns, and inline help; progress notifications stream in over SSE.

Portal

API keys

Create or revoke Postgres-backed bcrypt keys. Plaintext is shown once, then never again.

Portal

Discovery

RFC 9728 protected-resource metadata and the upstream OIDC authorization-server document, rendered the way an MCP client will see them.

Portal

Config

Read-only YAML view of the running server, with secrets masked. Useful for sanity-checking what's actually loaded.

What's inside

Capabilities

The tools are intentionally boring. They return predictable output for predictable input, fail in well-defined ways when asked to, and log every call. That's enough to write end-to-end assertions about a gateway's behavior without depending on real upstream data.

12 tools, 4 categories

Identity (whoami, echo, headers), data (deterministic fixtures), failure modes (errors, slow, flaky), streaming (progress notifications, multi-block content).

Real auth, three ways

File-loaded API keys (constant-time compare), bcrypt-hashed Postgres-backed keys, and external OIDC delegation with JWKS caching. RFC 9728 protected-resource metadata so MCP clients can discover the issuer.

Audit log of every call

Postgres-backed timeline with sanitized parameters, identity, latency, response size, and source. Browse, filter, and chart it in the embedded React portal.

Streamable HTTP at the root

Mounted at /, with browsers redirected to /portal/ and MCP clients passing through. No path conventions to fight.

Built-in instructions

The MCP initialize response includes server-level instructions that clients surface to the LLM as system context, telling models these tools are test fixtures, not data sources.

By Plexara

Plexara is a commercial MCP server with configurable enrichment built in. mcp-test is what we use to verify Plexara's gateway behavior end-to-end; we ship it as OSS so anyone building MCP integrations can use the same fixture.

Why this exists

Why a separate test server

Pair mcp-test with the audit log and you can write end-to-end assertions about gateway behavior without running fragile real-data fixtures.

  • Tools that return the same output for the same input (fixed_response, lorem with a seed).
  • Tools that fail on demand and on a schedule (slow, flaky seeded for reproducibility).
  • Tools that emit progress notifications you can count (progress).
  • Tools that echo identity and headers so you can confirm what's being forwarded (whoami, headers).