> ## Documentation Index
> Fetch the complete documentation index at: https://mcpjam-docs-coming-from-mcp-inspector.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://github.com/MCPJam/inspector/tree/main/skills/mcp-inspector), which gives your agent full context on every command and workflow.

```bash theme={null}
npx skills add mcpjam/inspector --skill mcp-inspector
```

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

## Install

```bash theme={null}
# Global (gives you the mcpjam command)
npm i -g @mcpjam/cli

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

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

## Command groups

| Group                                            | Purpose                                                                                              | Key commands                                                                          |
| ------------------------------------------------ | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| [`server`](/cli/server-inspection)               | Triage connectivity and capabilities                                                                 | `probe`, `doctor`, `info`, `validate`, `ping`, `capabilities`, `export`               |
| [`xaa`](/cli/xaa)                                | Run the Cross-App Access (ID-JAG) debugger against an MCP server                                     | `run`                                                                                 |
| [`oauth`](/cli/oauth-conformance)                | Test OAuth flows and conformance                                                                     | `conformance`, `conformance-suite`, `login`, `metadata`, `proxy`                      |
| [`apps`](/cli/apps-conformance)                  | Validate MCP Apps metadata and resource wiring                                                       | `conformance`, `conformance-suite`                                                    |
| [`compat`](/cli/reference#compat-command)        | Check whether a server's tools and widgets work on each AI host                                      | `compat`                                                                              |
| [`inspector`](/cli/reference#inspector-commands) | Start, open, or stop the local Inspector from the CLI                                                | `open`, `start`, `stop`                                                               |
| [`eval`](/cli/reference#eval-commands)           | Author and run eval suites in your hosted MCPJam projects                                            | `create`, `list`, `run`, `status`                                                     |
| [`tunnel`](/cli/reference#tunnel)                | Expose a local MCP server through a public MCPJam tunnel URL, registered as a server in your project | `tunnel <url>`, `tunnel -- <command>`                                                 |
| [`tools`](/cli/tools-resources-prompts)          | Exercise the tool surface                                                                            | `list`, `call`                                                                        |
| [`resources`](/cli/tools-resources-prompts)      | Read resources and templates                                                                         | `list`, `read`, `templates`                                                           |
| [`prompts`](/cli/tools-resources-prompts)        | Fetch prompts                                                                                        | `list`, `get`                                                                         |
| [`protocol`](/cli/reference)                     | MCP protocol conformance checks                                                                      | `conformance`, `conformance-suite`                                                    |
| [`hosts`](/cli/reference#hosts-commands)         | Manage hosts in your hosted MCPJam projects                                                          | `list`, `get`, `create`, `update`, `delete`, `templates`                              |
| [`env`](/cli/reference#env-commands)             | Manage custom computer environments (Dockerfile images)                                              | `list`, `get`, `create`, `edit`, `build`, `logs`, `use`, `reset`, `promote`, `delete` |
| [`mcp`](/cli/mcp-server)                         | Run MCPJam as a stdio MCP server for agents (Claude Desktop, Claude Code, Cursor, ...)               | `mcp`                                                                                 |
| [`telemetry`](/cli/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:

```bash theme={null}
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)

```bash theme={null}
mcpjam server doctor --url https://your-server.com/mcp
```

Add auth when needed:

```bash theme={null}
# 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)

```bash theme={null}
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.

<Note>
  `oauth ...` and `protocol ...` are HTTP-only command groups. They do
  not accept stdio targets.
</Note>

## 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":

```bash theme={null}
# 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:

```bash theme={null}
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](/cli/mcp-server).

## What's next

* [MCPJam as an MCP server](/cli/mcp-server) — give MCP clients the testing engine over stdio
* [Server inspection](/cli/server-inspection) — probe, doctor, and diagnostics
* [OAuth conformance](/cli/oauth-conformance) — test your OAuth implementation
* [OAuth login](/cli/oauth-login) — authenticate and debug OAuth flows
* [MCP Apps conformance](/cli/apps-conformance) — validate `_meta.ui.resourceUri` and `ui://` resource wiring
* [Tools, resources & prompts](/cli/tools-resources-prompts) — exercise the connected surface
* [Full command reference](/cli/reference) — every flag for every command