CLI Overview

Stateless MCP server probing, debugging, OAuth, and conformance from your terminal

The mcpjam CLI is a stateless tool for inspecting, debugging, and testing MCP servers from the command line or CI. It covers the full lifecycle: connectivity checks, OAuth login, MCP Apps validation, tool/resource/prompt exploration, and protocol conformance.

Recommended: Use with Agent Skills

The easiest way to use the CLI is through the MCPJam skill, which gives your agent full context on every command and workflow.

npx skills add mcpjam/inspector --skill mcp-inspector

Once installed, your agent will know how and when to invoke mcpjam commands automatically.

Install

# Global (gives you the mcpjam command)
npm i -g @mcpjam/cli

# Or run without installing
npx -y @mcpjam/cli@latest --help

All examples in these docs use mcpjam directly. If you installed via npx, replace mcpjam with npx -y @mcpjam/cli@latest.

Command groups

Group	Purpose	Key commands
server	Triage connectivity and capabilities	probe, doctor, info, validate, ping, capabilities, export
oauth	Test OAuth flows and conformance	conformance, conformance-suite, login, metadata, proxy
apps	Validate MCP Apps metadata and resource wiring	conformance, conformance-suite
inspector	Start, open, or stop the local Inspector from the CLI	open, start, stop
tools	Exercise the tool surface	list, call
resources	Read resources and templates	list, read, templates
prompts	Fetch prompts	list, get
protocol	MCP protocol conformance checks	conformance, conformance-suite
telemetry	Inspect and configure anonymous CLI telemetry	status, disable, enable

Global flags

These flags apply to every command.

Flag	Default	Description
--timeout <ms>	30000	Request timeout in milliseconds
--rpc	off	Include raw JSON-RPC request/response logs in JSON output under _rpcLogs
--quiet	off	Suppress non-result progress output on stderr
--no-telemetry	off	Disable anonymous telemetry for this invocation
--format <format>	human on TTY, json when piped	Raw output format (json or human)
-v, --version		Print the CLI version

Output formats

The CLI auto-detects whether stdout is a terminal:

• Interactive terminal — defaults to --format human. For most commands this is pretty-printed JSON; server doctor and the OAuth conformance commands provide dedicated human-readable summaries.
• Piped or redirected (CI, | jq, agent invocation) — defaults to --format json, the full structured result.
• Conformance in CI — protocol conformance, protocol conformance-suite, oauth conformance, oauth conformance-suite, apps conformance, and apps conformance-suite support --reporter junit-xml and --reporter json-summary.
• Explicit --format always wins over the auto-detected default.

For agents: raw JSON is the source of truth. Human format is a lossy presentation layer. If you’re parsing output programmatically, pass --quiet --format json.

JSON-valued flags accept inline JSON, @path, or - for stdin. Use files or stdin for large payloads to avoid shell escaping issues:

echo '{"key":"value"}' | mcpjam tools call --url $URL --access-token $TOKEN \
  --tool-name my_tool --tool-args - --quiet --format json

Connecting to servers

The CLI supports two transport modes, selected by which flags you pass:

• --url ... selects HTTP.
• --command ... selects stdio.
• --transport http|stdio is optional and acts as an explicit override/validator when you want the CLI to reject mismatched flags early.

HTTP (Streamable HTTP / SSE)

mcpjam server doctor --url https://your-server.com/mcp

Add auth when needed:

# Static bearer token
mcpjam server doctor --url https://your-server.com/mcp --access-token $TOKEN

# OAuth tokens from a prior login
mcpjam server doctor --url https://your-server.com/mcp --oauth-access-token $TOKEN

# Custom headers
mcpjam server doctor --url https://your-server.com/mcp --header "X-API-Key: $KEY"

Stdio (local subprocess)

mcpjam server doctor --command node --args server.js --cwd /path/to/project -e API_KEY=$KEY

Stdio child processes inherit the parent shell environment by default. Use -e/--env to add values or override inherited ones for the spawned server. Structured debug artifacts only record the explicit env keys you pass through -e/--env; inherited shell variables are not enumerated.

oauth ... and protocol ... are HTTP-only command groups. They do not accept stdio targets.

Exit codes

Code	Meaning
0	Success / all checks passed
1	Command ran but reported a failure (e.g., server unhealthy, conformance failed)
2	Invalid arguments or configuration

Quick triage workflow

The fastest path from “I have a server URL” to “I know what’s wrong”:

# 1. One-shot health check (probe + connect + sweep)
mcpjam server doctor --url https://your-server.com/mcp

# 2. If oauth_required: get a token
mcpjam oauth login --url https://your-server.com/mcp \
  --protocol-version 2025-11-25 --registration dcr

# 3. Re-run doctor with the token
mcpjam server doctor --url https://your-server.com/mcp --oauth-access-token $TOKEN

# 4. Exercise tools directly
mcpjam tools list --url https://your-server.com/mcp --access-token $TOKEN
mcpjam tools call --url https://your-server.com/mcp --access-token $TOKEN \
  --tool-name my_tool --tool-args @params.json --quiet --format json

# 5. If the server exposes MCP Apps, validate the ui:// surface
mcpjam apps conformance --url https://your-server.com/mcp --access-token $TOKEN

# 6. Render one UI-capable tool result in Inspector's App Builder
mcpjam tools call --url https://your-server.com/mcp --access-token $TOKEN \
  --tool-name my_app_tool --tool-args @params.json --ui --quiet --format json

What’s next

• Server inspection — probe, doctor, and diagnostics
• OAuth conformance — test your OAuth implementation
• OAuth login — authenticate and debug OAuth flows
• MCP Apps conformance — validate _meta.ui.resourceUri and ui:// resource wiring
• Tools, resources & prompts — exercise the connected surface
• Full command reference — every flag for every command