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
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 tool metadata and ui:// resources | conformance, mcp-widget, chatgpt-widget |
tools | Exercise the tool surface | list, call |
resources | Read resources and templates | list, read, templates |
prompts | Fetch prompts | list, get |
apps | Render hosted-style widget HTML for MCP and ChatGPT apps | mcp-widget, chatgpt-widget |
protocol | MCP protocol conformance checks | conformance |
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 |
--format <format> | human on TTY, json when piped | Output format (json or human; junit-xml is available on OAuth conformance commands only) |
-v, --version | | Print the CLI version |
- 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.
- 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, always pass --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
# 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
-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 conformance 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 '{"key": "value"}'
# 5. If the server exposes MCP Apps, validate the ui:// surface
mcpjam apps conformance --url https://your-server.com/mcp --access-token $TOKEN
What’s next
