> ## Documentation Index
> Fetch the complete documentation index at: https://mcpjam-mintlify-docs-update-pr-2772-1782277917413.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` |
| [`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`                                      |
| [`inspector`](/cli/reference#inspector-commands) | Start, open, or stop the local Inspector from the CLI                                                | `open`, `start`, `stop`                                                 |
| [`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`                                      |
| [`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 only appears on interactive terminals (when stderr is a TTY) and 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