MCP Workbench

English | 한국어

A developer toolkit for testing, inspecting, and validating Model Context Protocol servers.

Think of it as a Swagger UI + CLI + agent interface for MCP.

Why MCP Workbench?

MCP is becoming the standard interface for AI models to connect with external tools. But the ecosystem still lacks proper developer tooling for testing and validating servers. MCP Workbench fills that gap — interactive inspection, contract testing, regression diffs, and CI-ready execution.

Tool	Interactive Debug	Saved Tests	Regression Diff	CI Runner
MCP Inspector	✓	—	—	—
MCP Workbench	✓	✓	✓	✓

Features

mcp-workbench inspect — connect to any MCP server and explore its capabilities, tools, resources, and prompts
mcp-workbench run — execute YAML-defined test suites with rich assertions
mcp-workbench generate — auto-generate YAML test spec scaffolds from a live server (tools, resources, prompts)
Assertion engine — status, jsonpath, executionError, protocolError, contentType, count, notEmpty, equals, schema, and more
Transport support — stdio (local servers), streamable-http (remote servers), legacy SSE
Client simulator — inject roots, sampling presets, and elicitation handlers so you can test server→client capability flows
CI-friendly — --json output, non-zero exit on failure, --bail flag
Protocol-accurate — implements MCP spec 2025-11-25 including capability negotiation, session lifecycle, and notification handling
Browser UI — full-featured web inspector with Protocol tab (DevTools-style request/response log), dark/light mode, and live test runner
Plugin system — extend with reporters (html, junit) and custom commands via --plugin or workbench.config.yaml

Installation

# Primary — scoped package
npm install -g @mcp-workbench/cli

# Alternative — convenience wrapper
npm install -g mcp-workbench-cli

Both provide the same mcp-workbench command.

Why not npm install -g mcp-workbench? The unscoped mcp-workbench name on npm is taken by an unrelated project (an MCP server aggregator). Our project is a testing/validation platform — a completely different tool. See docs/npm-distribution.md for details.

Quick Start

Try it now (zero install)

npx @mcp-workbench/cli inspect --command npx --args "-y @mcp-workbench/demo-mcp"

This connects to the bundled demo server and displays its tools, resources, and prompts — no installation required.

Inspect a server

# stdio (local server)
mcp-workbench inspect --command node --args "path/to/server.js"

# HTTP (remote server)
mcp-workbench inspect --transport streamable-http --url https://your-server.com/mcp

Example output:

  Server Info

  Name:     my-mcp-server
  Version:  1.0.0
  Protocol: 2025-11-25

  Capabilities

  ✓ tools (listChanged)
  ✓ resources (subscribe)
  ✓ prompts
  ○ completions
  ○ logging

  Tools (3)

  get_weather [read-only]
    Get current weather for a city
  create_file [destructive]
    Create or overwrite a file

Run a test suite

mcp-workbench run tests.yaml
mcp-workbench run tests.yaml --verbose
mcp-workbench run tests.yaml --json > results.json
mcp-workbench run tests.yaml --bail --timeout 5000

Try the included fixture against the demo server:

mcp-workbench run examples/fixtures/demo-mcp.yaml --verbose

Start the Web UI

MCP Workbench ships a browser-based inspector alongside the CLI. Start both servers in two terminals:

# Terminal 1 — API server
node apps/api/dist/index.js

# Terminal 2 — Web UI (opens at http://localhost:5173)
pnpm --filter @mcp-workbench/web dev

Then open http://localhost:5173 in your browser. Enter your server details on the Inspect page to connect and explore tools, resources, prompts, and the live Protocol log.

Test Specification Format

Test suites are YAML files with the mcp-workbench.dev/v0alpha1 schema.

apiVersion: mcp-workbench.dev/v0alpha1

server:
  transport: stdio
  command: node
  args:
    - dist/server.js

# or for remote:
# server:
#   transport: streamable-http
#   url: https://your-server.com/mcp
#   headersFromEnv:
#     Authorization: MCP_API_TOKEN

client:
  protocolVersion: "2025-11-25"

tests:
  - id: tools-list
    description: Server exposes at least one tool
    act:
      method: tools/list
    assert:
      - kind: status
        equals: success
      - kind: notEmpty
        path: $.tools

  - id: get-weather
    description: Weather tool returns text for a valid city
    act:
      method: tools/call
      tool: get_weather
      args:
        city: Seoul
    assert:
      - kind: executionError
        equals: false
      - kind: contentType
        contains: text
      - kind: jsonpath
        path: $.content[0].text
        matches: "Seoul"

  - id: invalid-input
    description: Tool returns execution error (not protocol error) for bad input
    act:
      method: tools/call
      tool: get_weather
      args:
        city: 12345
    assert:
      - kind: executionError
        equals: true
      - kind: protocolError
        equals: false

Assertion Reference

Kind	Description
`status`	`equals: success \| error` — overall call status
`executionError`	`equals: true \| false` — tool `isError` flag
`protocolError`	`equals: true \| false` — JSON-RPC error response
`jsonpath`	JSONPath query with `equals`, `contains`, `matches`, or `notEmpty`
`notEmpty`	target is non-empty string / array / object
`contentType`	checks `content[*].type` — `equals` or `contains`
`count`	array length — `equals`, `min`, `max`
`equals`	deep equality at optional `path`
`schema`	JSON Schema validation at optional `path`
`outputSchemaValid`	validates tool `structuredContent` against `outputSchema`

CLI Reference

`mcp-workbench inspect`

mcp-workbench inspect [options]

Options:
  --transport <kind>   stdio | streamable-http | sse  (default: stdio)
  --command <cmd>      Command to run (stdio)
  --args <args>        Space-separated arguments (stdio)
  --url <url>          Server URL (HTTP)
  --timeout <ms>       Request timeout
  --json               JSON output
  --lang <locale>      Output language: en | ko  (env: MCP_WORKBENCH_LANG)

`mcp-workbench run`

mcp-workbench run <spec-file> [options]

Options:
  --tags <tags>        Run only tests matching these comma-separated tags
  --ids <ids>          Run only tests with these comma-separated IDs
  --bail               Stop after first failure
  --timeout <ms>       Per-request timeout
  --json               JSON output (CI-friendly)
  -v, --verbose        Show all assertion details
  --lang <locale>      Output language: en | ko  (env: MCP_WORKBENCH_LANG)

`mcp-workbench generate`

mcp-workbench generate [options]

Options:
  --transport <kind>   stdio | streamable-http  (default: stdio)
  --command <cmd>      Command to run (stdio)
  --args <args>        Space-separated arguments (stdio)
  --url <url>          Server URL (HTTP)
  --header <h>         HTTP header "Key: Value" (repeatable)
  --timeout <ms>       Connection timeout
  --include <list>     Comma-separated: tools,resources,prompts
  --exclude <list>     Comma-separated capabilities to skip
  -o, --output <file>  Write spec to file
  --stdout             Print spec to stdout
  --overwrite          Overwrite existing output file

See docs/generate.md for the full guide.

Internationalization

CLI output is available in multiple languages.

# Korean output via flag
mcp-workbench run tests.yaml --lang ko

# Korean output via environment variable
MCP_WORKBENCH_LANG=ko mcp-workbench inspect --command mcp-workbench-demo

Locale	Language
`en`	English (default)
`ko`	Korean

Only user-facing CLI messages are translated. JSON output (--json), protocol payloads, and assertion keys are always in English.

To add a new locale, see docs/i18n.md.

Architecture

MCP Workbench is a pnpm monorepo.

Name	npm package	Description
MCP Workbench	Product name	The overall project brand
`@mcp-workbench/cli`	Primary npm package	Full CLI implementation
`mcp-workbench-cli`	Convenience wrapper	Thin forwarder to the scoped package
`mcp-workbench`	CLI command	Binary name installed by both packages
`mcp-workbench` / `mcp-workbench-vscode` / `mcp-workbench-mcp-server`	GitHub repos	Source code repositories

Internal libraries are published under @mcp-workbench/*.

apps/
  cli                  — CLI entry point (mcp-workbench command)
  web                  — Browser UI (Vite + React)
  api                  — API server bridging the UI to MCP packages

packages/
  protocol-kernel      — JSON-RPC 2.0 + MCP types, ProtocolKernel class
  session-engine       — Session lifecycle, Timeline recording
  transport-stdio      — stdio child-process transport
  transport-http       — Streamable HTTP + SSE transport
  assertions           — Assertion engine
  test-spec            — YAML spec types and parser
  client-simulator     — Roots / sampling / elicitation capability simulator

examples/
  demo-mcp          — Demo MCP server (tools, resources, prompts)
  fixtures/            — Example test specs

Web UI

MCP Workbench includes a browser-based inspector. Start the API server and the Vite dev server:

# Terminal 1 — API server
node apps/api/dist/index.js

# Terminal 2 — Web UI (http://localhost:5173)
pnpm --filter @mcp-workbench/web dev

Connect to any MCP server from the Inspect page, then browse Tools, Resources, Prompts, and watch the live Protocol log.

To try it with the demo server, enter these values on the Inspect page:

Field	Value
Transport	stdio
Command	`mcp-workbench-demo`
Args	(leave empty)

Protocol Inspector — the Protocol tab shows every MCP message (initialize, tools/call, resources/read, etc.) as a DevTools-style request/response log with syntax-highlighted JSON payloads, status indicators, and duration timings.

The UI supports dark and light mode — toggle with the ☀/☾ button in the sidebar.

External tools (editor extensions, CI scripts) should rely on the CLI JSON contract.

Plugins

MCP Workbench has an extensible plugin system for reporters and custom commands.

# Generate an HTML report after running tests
mcp-workbench run tests.yaml \
  --plugin @mcp-workbench/plugin-html-report \
  --reporter html

# Generate JUnit XML for CI (GitHub Actions, Jenkins, etc.)
mcp-workbench run tests.yaml \
  --plugin @mcp-workbench/plugin-junit \
  --reporter junit \
  --reporter-output test-results.xml

Or configure plugins permanently in workbench.config.yaml:

plugins:
  - "@mcp-workbench/plugin-html-report"
  - "@mcp-workbench/plugin-junit"

See docs/plugins.md for the full plugin guide including how to build your own.

VS Code Extension

The official VS Code extension is in a separate repository: mcp-workbench-vscode

Run specs from the editor title bar or Command Palette
Test Results tree view (suite → test → assertion)
Failed assertions appear in the Problems panel
Configurable CLI path and timeout

See docs/vscode-extension.md for details.

MCP Server (Agent Integration)

Use MCP Workbench from any MCP host (Claude Desktop, Cursor, etc.) via the companion mcp-workbench-mcp-server project.

It exposes the same inspect / generate / run capabilities as MCP tools so AI agents can drive the entire workflow:

Tool	Description
`inspect_server`	Summarise a server's capabilities
`generate_spec`	Generate a YAML test spec and return it as text
`run_spec`	Run a spec (inline text or file path) and return structured results
`explain_failure`	Classify failure causes (auth, placeholder, protocol, …)

# Claude Code
claude mcp add mcp-workbench -- npx -y @mcp-workbench/mcp-server

# OpenAI Codex CLI
codex mcp add mcp-workbench -- npx -y @mcp-workbench/mcp-server

# Claude Desktop / Cursor (claude_desktop_config.json or .cursor/mcp.json)
{
  "mcpServers": {
    "mcp-workbench": {
      "command": "npx",
      "args": ["-y", "@mcp-workbench/mcp-server"]
    }
  }
}

Entry points: @mcp-workbench/cli is the human-facing runner. mcp-workbench-mcp-server is the agent-facing adapter. Both use the same core engine.

Ecosystem

MCP Workbench provides multiple interfaces on top of a shared core engine:

Interface	Repository	npm	Description
CLI (human-facing)	mcp-workbench	`@mcp-workbench/cli`	Inspect, test, validate from the terminal
VS Code (developer-facing)	mcp-workbench-vscode	—	Interactive workflow in the editor
MCP Server (agent-facing)	mcp-workbench-mcp-server	`@mcp-workbench/mcp-server`	Expose capabilities to AI agents

Contributing

See CONTRIBUTING.md.

License

Apache-2.0

Name		Name	Last commit message	Last commit date
Latest commit History 79 Commits
.github/workflows		.github/workflows
apps		apps
docs		docs
examples		examples
packages		packages
plugins		plugins
scripts		scripts
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.ko.md		README.ko.md
README.md		README.md
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
tsconfig.base.json		tsconfig.base.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

MCP Workbench

Why MCP Workbench?

Features

Installation

Quick Start

Try it now (zero install)

Inspect a server

Run a test suite

Start the Web UI

Test Specification Format

Assertion Reference

CLI Reference

`mcp-workbench inspect`

`mcp-workbench run`

`mcp-workbench generate`

Internationalization

Architecture

Web UI

Plugins

VS Code Extension

MCP Server (Agent Integration)

Ecosystem

Contributing

License

About

Uh oh!

Releases 4

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

MCP Workbench

Why MCP Workbench?

Features

Installation

Quick Start

Try it now (zero install)

Inspect a server

Run a test suite

Start the Web UI

Test Specification Format

Assertion Reference

CLI Reference

mcp-workbench inspect

mcp-workbench run

mcp-workbench generate

Internationalization

Architecture

Web UI

Plugins

VS Code Extension

MCP Server (Agent Integration)

Ecosystem

Contributing

License

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 4

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`mcp-workbench inspect`

`mcp-workbench run`

`mcp-workbench generate`

Packages