@mcpjam/cli weekly downloads statistics

@mcpjam/cli

Test, debug, and validate MCP servers locally, or manage MCPJam Cloud via mcpjam cloud. Health checks, OAuth conformance, tool-surface diffing, and structured triage from the terminal or CI.

Install

npm i -g @mcpjam/cli

Or run without installing:

npx -y @mcpjam/cli@latest --help

Commands

Local MCP testing stays at the top level. Most account-bound commands live under mcpjam cloud; hosted readiness is the root-level exception. See the 4.0 migration guide.

$ mcpjam --help

Usage: mcpjam [options] [command]

Test, debug, and validate MCP servers locally, or manage MCPJam Cloud via `mcpjam cloud`. Health checks, OAuth conformance, tool-surface diffing, and structured triage from the terminal or CI.

Options:
  -v, --version      output the CLI version
  --timeout <ms>     Request timeout in milliseconds (default: 30000)
  --rpc              Include RPC logs in JSON output
  --quiet            Suppress non-result progress output
  --no-telemetry     Disable anonymous usage telemetry
  --format <format>  Output format
  -h, --help         display help for command

Local MCP testing:
  server             Inspect MCP server connectivity and capabilities
  tools              List and invoke MCP server tools
  resources          List and read MCP resources
  subscriptions      Open a long-lived MCP subscription and stream its notifications
  compat             Check whether an MCP server's tools and widgets work on each AI host
  prompts            List and fetch MCP prompts
  apps               Validate MCP Apps metadata and resource wiring
  tasks              Create, inspect and drive MCP Tasks
  oauth              Run MCP OAuth login, proxy, and conformance flows
  xaa                Run the Cross-App Access (ID-JAG) debugger against an MCP server
  protocol           MCP protocol inspection and conformance checks
  readiness          Grade a server or plugin against a publisher's directory

MCPJam Cloud:
  cloud              MCPJam Cloud account commands (login, projects, evals, tunnels)

CLI:
  inspector          Start or attach to the local MCPJam Inspector
  mcp                Run MCPJam as an MCP server over stdio
  telemetry          Inspect and configure anonymous CLI telemetry

mcpjam oauth login authenticates against an MCP server. mcpjam cloud login authenticates your MCPJam account. Run mcpjam cloud --help for the Cloud groups.

Quick start

# Probe: is the server reachable? What transport? Is OAuth configured?
mcpjam server probe --url https://your-server.com/mcp

# Health check: MCP handshake, tool/resource/prompt sweep, exit code 0 or fail
mcpjam server doctor --url https://your-server.com/mcp --access-token $TOKEN

# OAuth login
mcpjam oauth login --url https://your-server.com/mcp --protocol-version 2025-11-25

# MCP Apps conformance
mcpjam apps conformance --url https://your-server.com/mcp --access-token $TOKEN

# Render a UI-capable tool result in Inspector
mcpjam tools call --url https://your-server.com/mcp --access-token $TOKEN \
  --tool-name create_view --tool-args @params.json --ui --quiet --format json

# List tools with full schemas
mcpjam tools list --url https://your-server.com/mcp --access-token $TOKEN --format json

# Run MCPJam itself as a stdio MCP server (for Claude Desktop, Claude Code, Cursor, ...)
mcpjam mcp

# MCPJam Cloud (account-bound)
mcpjam cloud login
mcpjam cloud projects list
mcpjam cloud eval run --suite smoke

Why

MCP servers don't have built-in health checks, OAuth conformance tests, or deploy-time regression detection. mcpjam adds those.

What it does

CI gate on every deploy

Run server doctor in your pipeline. It probes connectivity, runs the MCP handshake, and sweeps every tool, resource, and prompt. Exit code 0 or the build fails.

mcpjam server doctor --url $MCP_SERVER_URL --access-token $TOKEN --format json

Catch breaking changes before they ship

server export snapshots your entire tool surface as diffable JSON. A renamed parameter or changed description shows up in the diff.

mcpjam server export --url $URL --access-token $TOKEN > before.json
# deploy...
mcpjam server export --url $URL --access-token $TOKEN > after.json
diff <(jq -S . before.json) <(jq -S . after.json)

OAuth conformance across the full matrix

Cover the full registration × protocol version × auth mode matrix from a single config file. Outputs JUnit XML.

mcpjam oauth conformance-suite --config ./oauth-matrix.json --reporter junit-xml > report.xml

Verify tokens work end-to-end

OAuth can succeed while tools/list returns 401 because the audience, scope, or session init is wrong. --verify-call-tool completes the full chain (OAuth, MCP connect, tool call) and reports which step fails.

mcpjam oauth conformance --url $URL --protocol-version 2025-11-25 \
  --registration dcr --verify-call-tool your_critical_tool

Protocol version compatibility

MCP has shipped three protocol versions (2025-03-26, 2025-06-18, 2025-11-25). Clients upgrade on their own schedule. Declare the version matrix once and test on every push.

{
  "flows": [
    { "label": "2025-03-26/dcr", "protocolVersion": "2025-03-26", "registrationStrategy": "dcr" },
    { "label": "2025-06-18/dcr", "protocolVersion": "2025-06-18", "registrationStrategy": "dcr" },
    { "label": "2025-11-25/cimd", "protocolVersion": "2025-11-25", "registrationStrategy": "cimd" }
  ]
}

Structured debug artifacts

--debug-out captures a JSON artifact with every request and response in the OAuth and MCP flow. Attach it to a ticket instead of writing reproduction steps.

mcpjam oauth login --url $URL --protocol-version 2025-11-25 \
  --registration dcr --debug-out oauth-debug.json

Incident triage…