CLI Overview

The mcpjam CLI is two invocations. Local MCP testing stays at the top level: inspect, debug, and test MCP servers from the command line or CI (connectivity, OAuth, MCP Apps, tools/resources/prompts, protocol conformance). Most local commands are one-shot; mcpjam mcp and subscriptions listen keep a process open. Account-bound commands live under mcpjam cloud and talk to your MCPJam account. There are no compatibility aliases for the old Cloud paths — see Migrating to CLI 4.0.

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

To convert existing promptfoo, pytest, Jest, or CSV tests, use the MCP eval import skill.

npx skills add mcpjam/inspector --skill mcpjam-eval-import

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

Local MCP testing

These stay at the program root. They reject --api-key / --api-url / --project.

Group	Purpose	Key commands
`server`	Triage connectivity and capabilities	`probe`, `doctor`, `info`, `validate`, `ping`, `capabilities`, `export`
`tools`	Exercise the tool surface	`list`, `call`
`resources`	Read resources and templates	`list`, `read`, `templates`
`prompts`	Fetch prompts	`list`, `get`
`subscriptions`	Open a long-lived MCP subscription and stream notifications	`listen`
`tasks`	Drive MCP Tasks and validate the tasks wire	`list`, `get`, `cancel`, `conformance`
`apps`	Validate MCP Apps metadata and resource wiring	`conformance`, `conformance-suite`
`oauth`	Test OAuth flows and conformance against an MCP server	`conformance`, `conformance-suite`, `login`, `metadata`, `proxy`
`protocol`	MCP protocol conformance checks	`conformance`, `conformance-suite`
`readiness`	Grade a server against a publisher’s directory. Hosted `start` / `status` / `list` / `cancel` / `report` stay here (leaf `--api-key`; no Cloud project link)	`check`, `start claude`, `start openai`, `status`, `list`, `cancel`, `report`
`xaa`	Run the Cross-App Access (ID-JAG) debugger against an MCP server	`run`
`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`
`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`

MCPJam Cloud

Account-bound commands. Declare --api-key / --api-url on mcpjam cloud (before or after descendants). mcpjam oauth login is MCP-server OAuth; mcpjam cloud login is your MCPJam account.

Group	Purpose	Key commands
`cloud`	Account, project link, and workspace	`login`, `logout`, `whoami`, `link`, `status`, `organizations`, `projects`, `sessions`
`cloud eval`	Author and run eval suites in your hosted MCPJam projects	`create`, `list`, `run`, `status`
`cloud tunnel`	Expose a local MCP server through a public MCPJam tunnel URL, registered as a server in your project	`tunnel --server <name> <url>`, `tunnel --server <name> -- <command>`
`cloud hosts`	Manage hosts in your hosted MCPJam projects	`list`, `get`, `create`, `update`, `delete`, `templates`
`cloud environments`	Manage project environments — the host + servers + pinned skills/plugins bundles eval suites and journeys run against	`list`, `get`, `resolve`, `create`, `update`, `archive`, `restore`
`cloud images`	Manage custom Computer sandbox images (blueprints)	`list`, `get`, `create`, `validate`, `edit`, `build`, `logs`, `use`, `reset`, `promote`, `delete`

Also under mcpjam cloud: journeys, scenarios, personas, swarms, user-testing. Full flag tables are in the command reference.

Cloud credentials and API URL

--api-key and --api-url are declared on mcpjam cloud and work before or after descendants (mcpjam cloud --api-key sk_… eval list and mcpjam cloud eval list --api-key sk_… are the same). Local commands, including hosted readiness, reject those flags at the program root. Hosted readiness still takes leaf --api-key. Credential precedence for Cloud commands:

--api-key — must be an sk_ key. A mcpjam_… legacy key is a usage error.
MCPJAM_API_KEY — same sk_ rule. A legacy value in this env var is ignored (with a warning) so SDK eval reporting can still use it.
Stored OAuth from mcpjam cloud login
Missing — Cloud commands fail with login guidance before they hit the network (mcpjam cloud status reports missing instead)

API URL precedence:

--api-url
MCPJAM_API_URL
The apiUrl stored with the OAuth login (only when that login is the credential)
https://app.mcpjam.com/api/v1

An explicit --api-url or MCPJAM_API_URL that is not an http(s) URL is a usage error for commands that talk to the network (exit 2). mcpjam cloud status uses the same checks but stays network-free: it still emits the complete JSON report, sets ok: false, includes credential.valid / deployment.valid plus an error string, and exits 1. Missing credentials are informational (credential.valid: null) and successful. Successful Cloud commands print an audience line to stderr (Using MCPJam Cloud as … · project: … · <apiUrl>). --quiet suppresses it. Machine-readable JSON stays on stdout. cloud status redacts API keys.

Cloud project scope

Most Cloud commands pick one project:

--project <id-or-name>
An explicit project field in --file / --json
MCPJAM_PROJECT
The nearest valid .mcpjam/project.json
Automatic — the most recently updated project you can see

Empty --project or MCPJAM_PROJECT is a usage error. MCPJAM_PROJECT_ID does not select a Cloud CLI project (it is SDK eval reporting only).

mcpjam cloud login
mcpjam cloud link                  # writes .mcpjam/project.json (no secrets)
mcpjam cloud status                # zero-network: credential, deployment, selector
mcpjam cloud eval list             # uses the link
mcpjam cloud link --remove

mcpjam cloud eval run-inspection commands (status, cancel, judge, iterations, gate, compare, trace, steps, screenshot, video) follow the same rule — --project is optional. mcpjam cloud sessions list does too; --all-projects restores a cross-project listing and cannot be combined with --project. Hosted readiness never reads the project link.

What `--host` means

--host is not one flag. The meaning depends on the command:

Where	What it selects
`server`, `tools`, `resources`, `prompts`	An AI client (`claude`, `chatgpt`, `cursor`, …). The CLI sends that host’s `clientInfo`, capabilities, and protocol version in `initialize`.
`compat --host`	Which AI clients to report. Repeatable; default is all.
`cloud eval --host`, `cloud journeys`, `cloud scenarios`	A saved project Host (`<id-or-name>`), the client config an eval or journey is stamped with.
`cloud environments --host-id`	The project Host id the environment runs as. Distinct from eval’s `--host`.

--host on a local command is mutually exclusive with --client-capabilities. A Cloud --host is mutually exclusive with --server / --environment when those already supply a closed server set.

Global flags

These flags apply to every command. Cloud credentials --api-key / --api-url are declared on mcpjam cloud, not the program root.

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
Migrating to CLI 4.0 — command-path and flag changes under mcpjam cloud
Full command reference — every flag for every command

Guides

Reference

Recommended: Use with Agent Skills

Install

Command groups

Local MCP testing

MCPJam Cloud

Cloud credentials and API URL

Cloud project scope

What `--host` means

Global flags

Output formats

Connecting to servers

HTTP (Streamable HTTP / SSE)

Stdio (local subprocess)

Update notifications

Exit codes

Quick triage workflow

Use from an MCP client instead of a shell

What’s next

​Recommended: Use with Agent Skills

​Install

​Command groups

​Local MCP testing

​MCPJam Cloud

​Cloud credentials and API URL

​Cloud project scope

​What --host means

​Global flags

​Output formats

​Connecting to servers

​HTTP (Streamable HTTP / SSE)

​Stdio (local subprocess)

​Update notifications

​Exit codes

​Quick triage workflow

​Use from an MCP client instead of a shell

​What’s next

Recommended: Use with Agent Skills

Install

Command groups

Local MCP testing

MCPJam Cloud

Cloud credentials and API URL

Cloud project scope

What `--host` means

Global flags

Output formats

Connecting to servers

HTTP (Streamable HTTP / SSE)

Stdio (local subprocess)

Update notifications

Exit codes

Quick triage workflow

Use from an MCP client instead of a shell

What’s next