@mcpjam/cli

Test, debug, and validate MCP servers. Health checks, OAuth conformance, tool-surface diffing, and structured triage from the terminal or CI.

Install

Or run without installing:

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

Commands

$ mcpjam --help

Usage: mcpjam [options] [command]

Test, debug, and validate MCP servers. 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
  --format <format>  Output format
  -h, --help         display help for command

Commands:
  server             Inspect MCP server connectivity and capabilities
  tools              List and invoke MCP server tools
  resources          List and read MCP resources
  prompts            List and fetch MCP prompts
  apps               MCP Apps utilities, widget extraction, and conformance checks
  oauth              Run MCP OAuth login, proxy, and conformance flows
  protocol           MCP protocol inspection and conformance checks

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

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

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 --format 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

Separate your failures from host-side failures. --rpc records what your server returned (transport type, status codes, raw JSON-RPC pairs) as a structured artifact for postmortems.

mcpjam server doctor --url $URL --access-token $TOKEN --rpc --out incident-triage.json

Tool surface audit

Pipe the full schema inventory into your own linter, review it in a PR, or check whether descriptions are clear enough for tool selection.

mcpjam tools list --url $URL --access-token $TOKEN --format json \
  | jq '.tools[] | {name, description, inputSchema}'

GitHub Actions

name: MCP Health Check

on:
  push:
    branches: [main]
  pull_request:

jobs:
  mcp-doctor:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: OAuth login (headless)
        run: |
          set -euo pipefail
          npx -y @mcpjam/cli@latest oauth login \
            --url ${{ secrets.MCP_SERVER_URL }} \
            --protocol-version 2025-11-25 \
            --registration dcr \
            --auth-mode headless \
            --format json > /tmp/oauth-result.json
          TOKEN=$(jq -r '.credentials.accessToken // empty' /tmp/oauth-result.json)
          rm -f /tmp/oauth-result.json
          if [ -z "$TOKEN" ]; then
            echo "::error::OAuth login did not return an access token"
            exit 1
          fi
          echo "::add-mask::$TOKEN"
          echo "MCP_TOKEN=$TOKEN" >> "$GITHUB_ENV"

      - name: Run doctor
        run: npx -y @mcpjam/cli@latest server doctor --url ${{ secrets.MCP_SERVER_URL }} --access-token $MCP_TOKEN --format json

If you already have a refresh token, you can skip the login step and pass it directly:

mcpjam server doctor --url $URL --refresh-token $REFRESH_TOKEN --client-id $CLIENT_ID --client-secret $CLIENT_SECRET --format json

See the full CI documentation for all authentication options.

Documentation

Full docs at docs.mcpjam.com/cli.