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
xaa	Run the Cross-App Access (ID-JAG) debugger against an MCP server	run
oauth	Test OAuth flows and conformance	conformance, conformance-suite, login, metadata, proxy
apps	Validate MCP Apps metadata and resource wiring	conformance, conformance-suite
compat	Check whether a server’s tools and widgets work on each AI host	compat
inspector	Start, open, or stop the local Inspector from the CLI	open, start, stop
eval	Author and run eval suites in your hosted MCPJam projects	create, list, run, status
tunnel	Expose a local MCP server through a public MCPJam tunnel URL, registered as a server in your project	tunnel <url>, tunnel -- <command>
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
hosts	Manage hosts in your hosted MCPJam projects	list, get, create, update, delete, templates
env	Manage custom computer environments (Dockerfile images)	list, get, create, edit, build, logs, use, reset, promote, delete
mcp	Run MCPJam as a stdio MCP server for agents (Claude Desktop, Claude Code, Cursor, …)	mcp
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. tools call also accepts --tool-args-stdin as a shorthand for --tool-args -. 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.

Update notifications

After a successful command, the CLI checks whether a newer version of @mcpjam/cli is available and prints a notice to stderr when one is found:

Update available: @mcpjam/cli 1.2.0 -> 1.3.0
Run npm install -g @mcpjam/cli to update

The check is non-blocking: version data is fetched in a detached background process and cached locally for 24 hours, so it never slows down your commands. The notice is written to stderr only and never touches stdout or JSON output, so it is safe for both interactive terminals and AI agents (Claude Code, Cursor, etc.) that capture stderr. It is suppressed automatically in CI.

To opt out, set one of these environment variables before running any command:

Variable	Effect
MCPJAM_NO_UPDATE_CHECK=1	Disable update checks for @mcpjam/cli
NO_UPDATE_NOTIFIER=1	Disable update checks (conventional npm opt-out)
CI=true	Automatically suppressed in CI environments

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.
# --ui opens Inspector by default in a TTY; add --no-open if browser automation already opened it.
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

Use from an MCP client instead of a shell

If your agent speaks MCP but can’t run shell commands (Claude Desktop, chat clients), run the same testing engine as a stdio MCP server:

npx -y @mcpjam/cli@latest mcp

Connections to servers under test stay open between tool calls, so agents can also observe notifications and session behavior that one-shot CLI commands can’t. See MCPJam as an MCP server.

What’s next

• MCPJam as an MCP server — give MCP clients the testing engine over stdio
• 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