> ## 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. # Command Reference > Complete flag reference for every mcpjam CLI command Complete flag tables for every `mcpjam` command. For guides and recipes, see the individual command pages. ## Global flags | Flag | Default | Description | | ------------------- | --------------------------------- | --------------------------------------------------------- | | `--timeout ` | `30000` | Request timeout in milliseconds | | `--rpc` | off | Include raw JSON-RPC 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 ` | `human` on TTY, `json` when piped | Raw output format (`json` or `human`) | | `-v, --version` | | Print the CLI version | *** ## `server` commands All server commands accept the shared connection flags below, plus command-specific options. ### Shared connection flags | Flag | Description | | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------- | | `--transport ` | Explicit transport type (`http` or `stdio`) | | `--url ` | HTTP MCP server URL | | `--access-token ` | Bearer access token | | `--oauth-access-token ` | OAuth bearer access token | | `--refresh-token ` | OAuth refresh token | | `--client-id ` | OAuth client ID (with `--refresh-token`) | | `--client-secret ` | OAuth client secret (with `--refresh-token`) | | `--credentials-file ` | Load OAuth credentials from a file created by `oauth login --credentials-out` or `oauth conformance --credentials-out` | | `--header
` | HTTP header `Key: Value` (repeatable) | | `--client-capabilities ` | Client capabilities as inline JSON, `@path`, or `-` for stdin | | `--command ` | Stdio server command | | `--args ` | Preferred stdio command arguments | | `--command-args ` | Legacy stdio command argument (repeatable) | | `-e, --env ` | Stdio environment `KEY=VALUE` values | | `--cwd ` | Working directory for the stdio child process | Transport selection is inferred from `--url` vs `--command` when `--transport` is omitted. Use `--transport http|stdio` when you want an explicit validation step. For stdio targets, child processes inherit the parent shell environment by default. `-e/--env` adds or overrides child env values, and structured debug artifacts only record the explicit env keys you passed on the command line. `--credentials-file` cannot be combined with individual token flags (`--access-token`, `--oauth-access-token`, `--refresh-token`, `--client-id`, `--client-secret`). The CLI rejects conflicting auth sources upfront. ### `server probe` No additional flags beyond shared connection flags. ### `server doctor` | Flag | Description | | -------------- | ---------------------------------------- | | `--out ` | Write the doctor JSON artifact to a file | ### `server info` No additional flags. ### `server validate` No additional flags. ### `server ping` No additional flags. ### `server capabilities` No additional flags. ### `server export` No additional flags. *** ## `tools` commands ### `tools list` Uses shared connection flags, plus: | Flag | Description | | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--host ` | Connect as this host (e.g. `claude`, `chatgpt`, `cursor`) — sends its `clientInfo`, `clientCapabilities`, and protocol version in `initialize`, and hides app-only tools its model can't see. Mutually exclusive with `--client-capabilities`. | | `--cursor ` | Pagination cursor | | `--model-id ` | Model ID used for token counting | When `--host` is set, the output includes a `host` field and a `toolsDroppedVisibility` count. Hosts that opt out of visibility filtering (e.g. `cursor`) keep all tools. ### `tools call` | Flag | Description | | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--host ` | Connect as this host — sends its identity/capabilities/protocol in `initialize`, and rejects app-only tools the host's model can't call. Mutually exclusive with `--client-capabilities`. | | `--tool-name ` | Name of the tool to call | | `--name ` | Legacy alias for `--tool-name` | | `--tool-args ` | Tool arguments as inline JSON, `@path`, or `-` for stdin | | `--params ` | Legacy alias for `--tool-args` | | `--tool-args-stdin` | Read tool arguments JSON from stdin | | `--validate-response` | Validate the MCP tool-call envelope returned by the server | | `--expect-success` | Fail when the tool result reports `isError` | | `--reporter ` | `json-summary` or `junit-xml` validation report output | | `--debug-out ` | Write debug artifact to file | | `--ui` | Attach to Inspector and render the completed tool result in App Builder; opens a browser by default in a TTY | | `--require-render` | Treat skipped Inspector renders as errors (requires `--ui`) | | `--open` | Open Inspector in the system browser before rendering (default with `--ui` in a TTY) | | `--no-open` | Start/use Inspector without opening a system browser | | `--attach-only` | Require an already-running Inspector browser client; do not start or open Inspector | | `--inspector-url ` | Local Inspector backend/API base URL | | `--frontend-url ` | Inspector frontend/browser base URL; skips frontend discovery | | `--server-name ` | Server name to use inside Inspector | | `--protocol ` | Render protocol: `mcp-apps` or `openai-sdk` | | `--device ` | Render device: `mobile`, `tablet`, `desktop`, or `custom` | | `--theme ` | Render theme: `light` or `dark` | | `--locale ` | Render locale | | `--time-zone ` | Render IANA timezone | Plus shared connection flags. Without `--ui`, `tools call` returns the raw tool result. With `--ui`, it opens Inspector by default in a TTY and returns a compact envelope with `result`, `inspectorBrowserUrl`, and `inspectorRender` status. `inspectorRender.status` is `rendered` when Inspector accepted the render, `skipped` when the tool succeeded but Inspector had no active browser client, an unsatisfied render precondition, or a render timeout, and `error` for non-recoverable render command failures. `inspectorRender.remediation` is always present and is one of `open_browser`, `retry`, `reconnect_server`, or `none`. Skipped renders are emitted as a stable root `warning` plus `inspectorRender.warning`, both with the shape `{ code, message, remediation, browserUrl?, hasActiveClient?, inspectorStarted? }`. Stable skipped-render codes are `no_active_client`, `timeout`, `disconnected_server`, and `unsupported_in_mode`. Skipped renders keep the tool-call exit code unless `--require-render` is set; tool failures, validation failures, non-skippable render command errors, and `--require-render` skipped renders all exit nonzero. `--attach-only` is an exception to the skipped-render rule for `no_active_client`: by default a missing browser client yields `inspectorRender.status = "skipped"` with `inspectorRender.remediation = "open_browser"`, but when `--attach-only` is set, `no_active_client` is treated as non-skippable, surfaces as a root `error` (not a downgraded `warning`), and exits nonzero like other non-skippable render failures. `--inspector-url` points to the Inspector backend/API; pass `--frontend-url` when you already know the browser/client URL and want to skip health-advertised frontend checks and local dev port discovery. Use `--no-open` when browser automation already opened `inspectorBrowserUrl`; use `--attach-only` when startup, browser opening, and discovery should all be disallowed. Default non-TTY `--ui` runs do not open a browser unless `--open` is passed. When `--open` is in effect (default in TTYs, opt-in elsewhere), the App Builder URL and the initial browser-client wait progress are emitted to stderr unless `--quiet` is set, regardless of whether stderr is a TTY; only the elapsed-seconds heartbeat is gated on stderr being a TTY. The Inspector path injects the completed tool result through `renderToolResult`; it does not call the tool a second time. Fresh tabs do not hydrate the injected render state; use the active Inspector client that received the render. Use `--debug-out` for the full render envelope including params and command responses. `--ui` cannot be combined with `--reporter`. ### Reading `tools call --ui` output as an agent Treat the tool result and the Inspector render as separate outcomes. An exit code of `0` means the tool call succeeded and no hard render error occurred; it does not, by itself, prove the UI rendered. Confirm UI delivery with `inspectorRender.status === "rendered"`. If `inspectorRender.status === "skipped"`, branch on `inspectorRender.remediation` or the stable root `warning.code`. If `--require-render` is set, the same skipped-render issue moves from root `warning` to root `error` and the command exits with code `1`. ```json theme={null} { "success": true, "command": "tools call", "inspectorUi": true, "inspectorBrowserUrl": "http://127.0.0.1:6274/#app-builder", "result": { "content": [{ "type": "text", "text": "view created" }] }, "inspectorRender": { "status": "skipped", "remediation": "open_browser", "mode": "active-client", "urlHydratesRender": false, "browserUrl": "http://127.0.0.1:6274/#app-builder", "hasActiveClient": false, "inspectorStarted": false, "warning": { "code": "no_active_client", "message": "Inspector has no active browser client. Open the Inspector App Builder URL in your browser, then rerun `tools call --ui`; or pass `--open` to let the CLI open a system browser.", "remediation": "open_browser", "browserUrl": "http://127.0.0.1:6274/#app-builder", "hasActiveClient": false, "inspectorStarted": false } }, "warning": { "code": "no_active_client", "message": "Inspector has no active browser client. Open the Inspector App Builder URL in your browser, then rerun `tools call --ui`; or pass `--open` to let the CLI open a system browser.", "remediation": "open_browser", "browserUrl": "http://127.0.0.1:6274/#app-builder", "hasActiveClient": false, "inspectorStarted": false } } ``` *** ## `resources` commands ### `resources list` Uses shared connection flags, plus: | Flag | Description | | ------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | `--host ` | Connect as this host — sends its identity/capabilities/protocol in `initialize`. Mutually exclusive with `--client-capabilities`. | | `--cursor ` | Pagination cursor | ### `resources read` | Flag | Description | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | `--host ` | Connect as this host — sends its identity/capabilities/protocol in `initialize`. Mutually exclusive with `--client-capabilities`. | | `--resource-uri ` | URI of the resource to read | | `--uri ` | Legacy alias for `--resource-uri` | Plus shared connection flags. ### `resources templates` Uses shared connection flags, plus: | Flag | Description | | ------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | `--host ` | Connect as this host — sends its identity/capabilities/protocol in `initialize`. Mutually exclusive with `--client-capabilities`. | | `--cursor ` | Pagination cursor | *** ## `prompts` commands ### `prompts list` Uses shared connection flags, plus: | Flag | Description | | ------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | `--host ` | Connect as this host — sends its identity/capabilities/protocol in `initialize`. Mutually exclusive with `--client-capabilities`. | | `--cursor ` | Pagination cursor | ### `prompts get` | Flag | Description | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | `--host ` | Connect as this host — sends its identity/capabilities/protocol in `initialize`. Mutually exclusive with `--client-capabilities`. | | `--prompt-name ` | Name of the prompt | | `--name ` | Legacy alias for `--prompt-name` | | `--prompt-args ` | Prompt arguments as inline JSON, `@path`, or `-` for stdin | Plus shared connection flags. *** ## `xaa` commands ### `xaa run` Run the Cross-App Access (ID-JAG) debugger: self-issue an ID-JAG, redeem it at the target authorization server (RFC 7523), and call the MCP server with the resulting access token. See the [XAA Debugger guide](/cli/xaa) for the trust setup, registration strategies, and CI usage. | Flag | Required | Default | Description | | --------------------------------------- | -------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `--url ` | Yes | | Target MCP server URL (the protected resource) | | `--issuer-base-url ` | Yes | | Origin the local mock IdP issues from. It must publish the CLI's local signing key — typically a running [local inspector](/cli/xaa#before-you-run-make-the-issuer-reachable), not your real IdP | | `--sub ` | Yes | | Simulated end-user subject identifier | | `--client-id ` | No | | OAuth client ID. Required for `preregistered`; rejected for `dcr`/`cimd` | | `--registration ` | No | `preregistered` | `preregistered`, `dcr`, or `cimd` | | `--client-metadata-url ` | No | | CIMD only: the Client ID Metadata Document URL to present as the `client_id` | | `--client-auth ` | No | `none` | CIMD only: `none` (public) or `private-key-jwt` (confidential — generates a local EC P-256 key, publishes it via the hosted reflector, and signs a `client_assertion`) | | `--cimd-metadata-origin ` | No | `https://app.mcpjam.com` | Confidential CIMD only: bare origin hosting the metadata-document reflector. An `http://` loopback origin is a dev-only opt-in; rejected when `--https-only` is set | | `--authz-server-issuer ` | No | | Target AS issuer. When set, protected-resource metadata discovery is skipped | | `--token-endpoint ` | No | | AS token endpoint. When set, AS-metadata discovery is skipped. Not valid with `dcr` or `cimd` | | `--email ` | No | | Simulated end-user email claim | | `--client-secret ` | No | | OAuth client secret presented at redemption | | `--token-endpoint-auth-method ` | No | | `client_secret_basic`, `client_secret_post`, or `none`. Not valid with `dcr` or `cimd` | | `--assertion-format ` | No | `oidc` | Identity assertion format: `oidc` (ID token) or `saml` (SAML 2.0 assertion) | | `--scopes ` | No | | Space-separated scope string | | `--https-only` | No | | Reject non-HTTPS / private targets | #### Registration strategies | Strategy | Description | | --------------- | --------------------------------------------------------------------------------------- | | `preregistered` | Supply a pre-registered `--client-id` (and optional `--client-secret`) | | `dcr` | Dynamic Client Registration (RFC 7591) — the CLI registers a client at the RAS each run | | `cimd` | Client ID Metadata Document — the client publishes its identity at a URL | #### Confidential CIMD (`--client-auth private-key-jwt`) When `--registration cimd --client-auth private-key-jwt` is used, the CLI loads or generates a local EC P-256 key pair (stored in `~/.mcpjam`). The public key is encoded into a reflector URL on `app.mcpjam.com`, which becomes the `client_id`. The CLI signs a `client_assertion` with the private key at token-redemption time; the private key never leaves the machine. ```bash theme={null} mcpjam inspector start # serves the issuer at http://localhost:6274/api/mcp/xaa mcpjam xaa run \ --url http://localhost:8080/mcp \ --issuer-base-url http://localhost:6274/api/mcp \ --sub user@example.com \ --registration cimd \ --client-auth private-key-jwt ``` For a cloud authorization server, expose the inspector origin through a tunnel and pass the public origin as `--issuer-base-url` — see [making the issuer reachable](/cli/xaa#before-you-run-make-the-issuer-reachable). **Key rotation:** the key is the identity. Deleting `~/.mcpjam/xaa-client-private.pem` or changing the `XAA_CLIENT_PRIVATE_KEY` environment variable generates a new `client_id`; any RAS-side allowlisting must be updated after rotation. *** ## `oauth` commands ### `oauth login` | Flag | Required | Default | Description | | ----------------------------- | -------- | -------------- | ------------------------------------------------------------------------ | | `--url ` | Yes | | MCP server URL | | `--protocol-version ` | Yes | | `2025-03-26`, `2025-06-18`, or `2025-11-25` | | `--registration ` | Yes | | `cimd`, `dcr`, or `preregistered` | | `--auth-mode ` | No | `interactive` | `headless`, `interactive`, or `client_credentials` | | `--client-id ` | No | | OAuth client ID | | `--client-secret ` | No | | OAuth client secret | | `--client-metadata-url ` | No | | CIMD metadata document URL | | `--redirect-url ` | No | Auto-generated | OAuth redirect URL | | `--scopes ` | No | | Space-separated scope string | | `--header
` | No | | HTTP header `Key: Value` (repeatable) | | `--step-timeout ` | No | `30000` | Per-step timeout | | `--verify-tools` | No | | After login, list tools | | `--verify-call-tool ` | No | | Also call the named tool | | `--credentials-out ` | No | | Write OAuth credentials to file (mode 0600); stdout has secrets redacted | | `--debug-out ` | No | | Write debug artifact to file | ### `oauth conformance` | Flag | Required | Default | Description | | ----------------------------- | -------- | -------------- | ---------------------------------------------------------------------------------------------------- | | `--url ` | Yes | | MCP server URL | | `--protocol-version ` | Yes | | `2025-03-26`, `2025-06-18`, or `2025-11-25` | | `--registration ` | Yes | | `cimd`, `dcr`, or `preregistered` | | `--auth-mode ` | No | `interactive` | `headless`, `interactive`, or `client_credentials` | | `--client-id ` | No | | OAuth client ID | | `--client-secret ` | No | | OAuth client secret | | `--client-metadata-url ` | No | | CIMD metadata document URL | | `--redirect-url ` | No | Auto-generated | OAuth redirect URL | | `--scopes ` | No | | Space-separated scope string | | `--header
` | No | | HTTP header `Key: Value` (repeatable) | | `--step-timeout ` | No | `30000` | Per-step timeout | | `--verify-tools` | No | | After OAuth, list tools | | `--verify-call-tool ` | No | | Also call the named tool | | `--conformance-checks` | No | | Run additional negative OAuth checks, including DCR redirect URI policy and redirect-mismatch probes | | `--credentials-out ` | No | | Write OAuth credentials to file (mode 0600); stdout has secrets redacted | | `--print-url` | No | | Print consent URL to stderr (interactive only) | | `--reporter ` | No | | `json-summary` or `junit-xml` CI report output | ### `oauth conformance-suite` | Flag | Required | Default | Description | | --------------------------- | -------- | ------- | ---------------------------------------------------------------------------------------- | | `--config ` | Yes | | Path to JSON config file | | `--verify-tools` | No | | Enable tool listing on all flows | | `--verify-call-tool ` | No | | Call the named tool after listing | | `--credentials-out ` | No | | Write OAuth credentials from the first flow that returns credentials to file (mode 0600) | | `--reporter ` | No | | `json-summary` or `junit-xml` CI report output | ### `oauth metadata` | Flag | Required | Description | | ------------- | -------- | --------------------------- | | `--url ` | Yes | OAuth metadata URL to fetch | ### `oauth proxy` / `oauth debug-proxy` | Flag | Required | Default | Description | | ------------------- | -------- | ------- | ----------------------------------------------------------- | | `--url ` | Yes | | OAuth request URL | | `--method ` | No | `GET` | HTTP method | | `--header
` | No | | HTTP header `Key: Value` (repeatable) | | `--body ` | No | | Request body as JSON, raw string, `@path`, or `-` for stdin | *** ## `protocol` commands ### `protocol conformance` | Flag | Required | Default | Description | | --------------------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------- | | `--url ` | Yes | | MCP server URL | | `--access-token ` | No | | Bearer access token | | `--credentials-file ` | No | | Load OAuth credentials from a file created by `oauth login --credentials-out` or `oauth conformance --credentials-out` | | `--header
` | No | | HTTP header `Key: Value` (repeatable) | | `--check-timeout ` | No | `15000` | Per-check timeout in milliseconds | | `--category ` | No | all | Restrict checks to one or more categories | | `--check-id ` | No | all | Restrict checks to one or more check IDs | | `--reporter ` | No | | `json-summary` or `junit-xml` CI report output | Use `--format json|human` for raw output and `--reporter json-summary|junit-xml` for CI reports. ### `protocol conformance-suite` | Flag | Required | Default | Description | | ----------------------- | -------- | ------- | ---------------------------------------------- | | `--config ` | Yes | | Path to JSON config file | | `--reporter ` | No | | `json-summary` or `junit-xml` CI report output | *** ## `apps` commands ### Shared connection flags | Flag | Description | | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------- | | `--transport ` | Explicit transport type (`http` or `stdio`) | | `--url ` | HTTP MCP server URL | | `--access-token ` | Bearer access token | | `--oauth-access-token ` | OAuth bearer access token | | `--refresh-token ` | OAuth refresh token | | `--client-id ` | OAuth client ID (with `--refresh-token`) | | `--client-secret ` | OAuth client secret (with `--refresh-token`) | | `--credentials-file ` | Load OAuth credentials from a file created by `oauth login --credentials-out` or `oauth conformance --credentials-out` | | `--header
` | HTTP header `Key: Value` (repeatable) | | `--client-capabilities ` | Client capabilities as inline JSON, `@path`, or `-` for stdin | | `--command ` | Stdio server command | | `--args ` | Preferred stdio command arguments | | `--command-args ` | Legacy stdio command argument (repeatable) | | `-e, --env ` | Stdio environment `KEY=VALUE` values | | `--cwd ` | Working directory for the stdio child process | Apps commands share the same transport inference rules as the rest of the CLI: `--url` implies HTTP, `--command` implies stdio, and `--transport` is an optional explicit override. ### `apps conformance` MCP Apps server-side conformance checks. Uses shared connection flags plus: | Flag | Description | | ----------------------- | -------------------------------------------------------- | | `--category ` | Check category to run (`tools`, `resources`). Repeatable | | `--check-id ` | Specific check id to run. Repeatable | | `--reporter ` | `json-summary` or `junit-xml` CI report output | Use `--format json|human` for raw output and `--reporter json-summary|junit-xml` for CI reports. ### `apps conformance-suite` | Flag | Required | Default | Description | | ----------------------- | -------- | ------- | ---------------------------------------------- | | `--config ` | Yes | | Path to JSON config file | | `--reporter ` | No | | `json-summary` or `junit-xml` CI report output | *** ## `compat` command Check whether an MCP server's tools and widgets work on each AI host. Uses shared server connection flags (see [`server` commands](#server-commands)) plus: | Flag | Description | | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | `--host ` | Only report this host ID. Repeat for several. Default: all. Valid IDs: `claude`, `chatgpt`, `cursor`, `copilot`, `codex`, `goose`, and others. | ```bash theme={null} mcpjam compat --url https://your-server.com/mcp mcpjam compat --url https://your-server.com/mcp --host claude --host chatgpt ``` The result includes a per-host `verdict` (`works`, `degraded`, `blocked`, or `unknown`), a `findings` list explaining each verdict, and a top-level `summary` count. When the tool list is truncated (more than 50 pages), verdicts that would otherwise be `works` are downgraded to `unknown`. *** ## `hosts` commands Manage the hosts saved in your hosted MCPJam projects. All `hosts` commands require an `sk_` API key (via `--api-key` or the `MCPJAM_API_KEY` environment variable) or a prior `mcpjam login`. ### Shared platform flags | Flag | Description | | ----------------- | ----------------------------------------------------------------- | | `--api-key ` | MCPJam `sk_` API key (overrides `MCPJAM_API_KEY`) | | `--api-url ` | MCPJam API base URL (defaults to `https://app.mcpjam.com/api/v1`) | ### `hosts templates` List the built-in host templates usable with `hosts create --template`. No additional flags. ### `hosts list` | Flag | Description | | ------------------------ | ------------------------------------------------------------------ | | `--project ` | Project name or ID (defaults to the most recently updated project) | ### `hosts get` | Flag | Required | Description | | ------------------------ | -------- | ------------------ | | `--host ` | Yes | Host name or ID | | `--project ` | No | Project name or ID | ### `hosts create` | Flag | Required | Description | | ------------------------ | -------- | -------------------------------------------------------------------------------- | | `--name ` | Yes | Display name for the new host | | `--project ` | No | Project name or ID | | `--template ` | No | Built-in template ID (see `hosts templates`), e.g. `claude`, `chatgpt`, `cursor` | | `--theme ` | No | Theme for the seeded config: `light` or `dark` (template only) | | `--file ` | No | Host config v2 JSON file (or `-` for stdin) | | `--json ` | No | Inline host config v2 JSON (or `@file`, or `-`) | Provide either `--template` or `--file`/`--json`, not both. ### `hosts update` | Flag | Required | Description | | ------------------------ | -------- | ----------------------------------------------------------- | | `--host ` | Yes | Host name or ID | | `--project ` | No | Project name or ID | | `--name ` | No | New display name | | `--file ` | No | Replacement host config v2 JSON (or `-` for stdin) | | `--json ` | No | Inline replacement host config v2 JSON (or `@file`, or `-`) | ### `hosts delete` | Flag | Required | Description | | ------------------------ | -------- | ------------------ | | `--host ` | Yes | Host name or ID | | `--project ` | No | Project name or ID | *** ## `env` commands Manage custom computer environments (Dockerfile images) in your hosted MCPJam projects. All `env` commands require an `sk_` API key (via `--api-key` or the `MCPJAM_API_KEY` environment variable) or a prior `mcpjam login`. ### Shared platform flags | Flag | Description | | ----------------- | ----------------------------------------------------------------- | | `--api-key ` | MCPJam `sk_` API key (overrides `MCPJAM_API_KEY`) | | `--api-url ` | MCPJam API base URL (defaults to `https://app.mcpjam.com/api/v1`) | ### `env list` | Flag | Description | | ------------------------ | ------------------------------------------------------------------ | | `--project ` | Project name or ID (defaults to the most recently updated project) | ### `env get` | Flag | Required | Description | | ---------------------------- | -------- | ---------------------- | | `--environment ` | Yes | Environment name or ID | | `--project ` | No | Project name or ID | ### `env create` | Flag | Required | Description | | ------------------------ | -------- | ------------------------------------------ | | `--name ` | Yes | Display name for the new environment | | `--file ` | Yes | Dockerfile path, or `-` to read from stdin | | `--project ` | No | Project name or ID | ### `env edit` | Flag | Required | Description | | ---------------------------- | -------- | ---------------------------------------------- | | `--environment ` | Yes | Environment name or ID | | `--project ` | No | Project name or ID | | `--name ` | No | New display name | | `--file ` | No | Replacement Dockerfile path (or `-` for stdin) | ### `env build` Trigger an image build for the environment (async). Poll `env logs` to check build status. | Flag | Required | Description | | ---------------------------- | -------- | ---------------------- | | `--environment ` | Yes | Environment name or ID | | `--project ` | No | Project name or ID | ### `env logs` Show an environment's builds (newest first) with their log preview. | Flag | Required | Description | | ---------------------------- | -------- | ---------------------- | | `--environment ` | Yes | Environment name or ID | | `--project ` | No | Project name or ID | ### `env use` Boot your computer from this environment. This rebuilds the computer — installed files are wiped. | Flag | Required | Description | | ---------------------------- | -------- | ---------------------- | | `--environment ` | Yes | Environment name or ID | | `--project ` | No | Project name or ID | ### `env reset` Reset your computer to its current image, wiping mutable state. | Flag | Required | Description | | ------------------------ | -------- | ------------------ | | `--project ` | No | Project name or ID | ### `env promote` Share a personal-draft environment with the whole project. Requires project admin permissions. | Flag | Required | Description | | ---------------------------- | -------- | ---------------------- | | `--environment ` | Yes | Environment name or ID | | `--project ` | No | Project name or ID | ### `env delete` Permanently delete an environment from a project. | Flag | Required | Description | | ---------------------------- | -------- | ---------------------- | | `--environment ` | Yes | Environment name or ID | | `--project ` | No | Project name or ID | *** ## `inspector` commands ### `inspector open` Start or attach to the local Inspector and open the UI. | Flag | Required | Description | | ----------------------- | -------- | -------------------------------- | | `--inspector-url ` | No | Local Inspector base URL | | `--tab ` | No | Open Inspector on a specific tab | ### `inspector start` Start the local Inspector in the background without opening a browser. | Flag | Required | Description | | ----------------------- | -------- | ------------------------ | | `--inspector-url ` | No | Local Inspector base URL | ### `inspector stop` Stop the local Inspector if it is running. | Flag | Required | Description | | ----------------------- | -------- | ------------------------ | | `--inspector-url ` | No | Local Inspector base URL | *** ## `eval` commands Author and run eval suites in your hosted MCPJam projects. All `eval` subcommands require an MCPJam API key (`--api-key` or `MCPJAM_API_KEY`). ### Shared platform flags | Flag | Description | | ----------------- | ----------------------------------------------------------------- | | `--api-key ` | MCPJam `sk_` API key (overrides `MCPJAM_API_KEY`) | | `--api-url ` | MCPJam API base URL (defaults to `https://app.mcpjam.com/api/v1`) | ### `eval create` Create a runnable eval suite from authored test cases. The suite is persisted and returned with a `suiteId`; it is **not** run. Execute it afterward with `eval run`. | Flag | Description | | ------------------------ | -------------------------------------------------------------------------------------- | | `--project ` | Project name or ID (defaults to the most recently updated project) | | `--file ` | Path to a suite definition JSON file (or `-` for stdin) | | `--json ` | Inline suite definition JSON (or `@file`, or `-` for stdin) | | `--name ` | Suite name (overrides the file) | | `--model ` | Suite-level default model, e.g. `anthropic/claude-haiku-4.5` (overrides the file) | | `--provider ` | Suite-level default provider (overrides the file; needed for bare or custom model ids) | | `--server ` | Project HTTP server names or IDs (overrides the file; repeatable) | Provide the suite definition via `--file` or `--json` (not both). The definition is a JSON object with at minimum `name`, `model`, `servers`, and `cases`. Servers must be HTTP; stdio servers are rejected before any write. ```bash theme={null} mcpjam eval create \ --json '{"name":"smoke","model":"anthropic/claude-haiku-4.5","servers":["My Server"],"cases":[{"title":"echo works","query":"Use the echo tool to say hi","expectedToolCalls":["echo"]}]}' \ --api-key $MCPJAM_API_KEY ``` ### `eval list` List the eval suites saved in a project. | Flag | Description | | ------------------------ | ------------------------------------------------------------------ | | `--project ` | Project name or ID (defaults to the most recently updated project) | ### `eval run` Start an asynchronous eval run of an existing suite. Responds immediately with a `runId`; poll status with `eval status`. | Flag | Required | Description | | ------------------------ | -------- | --------------------------------------------------------------------------- | | `--suite ` | Yes | Eval suite name or ID | | `--project ` | No | Project name or ID (defaults to the most recently updated project) | | `--server ` | No | Override the suite's saved server selection (HTTP servers only; repeatable) | ### `eval status` Get the status and summary of an eval run. | Flag | Required | Description | | ------------------------ | -------- | ----------------------------- | | `--run ` | Yes | Eval run ID (from `eval run`) | | `--project ` | Yes | Project name or ID | *** ## `tunnel` Expose a local MCP server through an MCPJam relay tunnel and register it as a server in your hosted project, so evals and chatboxes can target it. Requires an `sk_` API key or a prior `mcpjam login`. The tunnel stays up until Ctrl-C; the server record outlives the session (calls fail fast at the edge until you re-run, which revives the same URL slug with a fresh secret). ```bash theme={null} # HTTP target mcpjam tunnel http://localhost:9090/mcp --id my-server --project acme # stdio target (command goes after --) mcpjam tunnel --id everything --project acme -- npx -y @modelcontextprotocol/server-everything ``` | Flag | Required | Description | | ------------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--id ` | Yes | Server name to register in the project. An existing server with this name is pointed at the tunnel: its URL is overwritten, and stdio records are converted to HTTP. | | `--project ` | No | Project name or ID (defaults to the most recently updated project) | | `--api-key ` | No | MCPJam `sk_` API key (overrides `MCPJAM_API_KEY`) | | `--api-url ` | No | MCPJam API base URL (defaults to `https://app.mcpjam.com/api/v1`) | | `-e, --env ` | No | Stdio environment assignment in `KEY=VALUE` format (stdio targets only) | | `--cwd ` | No | Working directory for the stdio MCP server process (stdio targets only) | With `--format json`, a single machine-readable startup object (public URL, server ID, slug, project) is written to stdout; ongoing status goes to stderr in both formats. The public tunnel URL embeds a bearer secret and is stored on the project server record so the platform can call it. Every re-run rotates the secret and disconnects any previous tunnel session for the same server. *** ## `eval` commands All `eval` commands accept the shared platform flags below. ### Shared platform flags | Flag | Description | | ----------------- | ----------------------------------------------------------------- | | `--api-key ` | MCPJam `sk_` API key (overrides `MCPJAM_API_KEY`) | | `--api-url ` | MCPJam API base URL (defaults to `https://app.mcpjam.com/api/v1`) | ### `eval create` Create a runnable eval suite from authored test cases (does not run it). | Flag | Required | Description | | ------------------------ | -------- | ------------------------------------------------------------------ | | `--project ` | No | Project name or ID (defaults to the most recently updated project) | | `--file ` | No | Path to a suite definition JSON file (or `-` for stdin) | | `--json ` | No | Inline suite definition JSON (or `@file`, or `-` for stdin) | | `--name ` | No | Suite name (overrides the file) | | `--model ` | No | Suite-level default model (overrides the file) | | `--provider ` | No | Suite-level default provider (overrides the file) | | `--server ` | No | Project HTTP server names or IDs (overrides the file) | ### `eval list` List the eval suites saved in a project. | Flag | Required | Description | | ------------------------ | -------- | ------------------------------------------------------------------ | | `--project ` | No | Project name or ID (defaults to the most recently updated project) | ### `eval run` Start an eval run of an existing suite (asynchronous). | Flag | Required | Description | | ------------------------ | -------- | ------------------------------------------------------------------ | | `--suite ` | Yes | Eval suite name or ID | | `--project ` | No | Project name or ID (defaults to the most recently updated project) | | `--server ` | No | Override the suite's saved server selection (HTTP servers only) | ### `eval status` Get the status and summary of an eval run. | Flag | Required | Description | | ------------------------ | -------- | ----------------------------- | | `--run ` | Yes | Eval run ID (from `eval run`) | | `--project ` | Yes | Project name or ID | ### `eval iterations` List per-iteration results for an eval run (pass/fail, tool calls, tokens, latency). Results are paginated. | Flag | Required | Description | | ------------------------ | -------- | ------------------------------------------ | | `--run ` | Yes | Eval run ID (from `eval run`) | | `--project ` | Yes | Project the run belongs to (name or ID) | | `--cursor ` | No | Pagination cursor from a previous response | | `--limit ` | No | Max iterations per page (1–200) | ### `eval trace` Fetch the full trace for one eval iteration (complete message history and spans). Can be large. | Flag | Required | Description | | ------------------------ | -------- | --------------------------------------- | | `--run ` | Yes | Eval run ID (from `eval run`) | | `--iteration ` | Yes | Iteration ID (from `eval iterations`) | | `--project ` | Yes | Project the run belongs to (name or ID) | ### `eval get` Show an eval suite's full settings. | Flag | Required | Description | | ------------------------ | -------- | ------------------------------------------------------------------ | | `--suite ` | Yes | Eval suite name or ID | | `--project ` | No | Project name or ID (defaults to the most recently updated project) | ### `eval update` Edit an eval suite's settings (only the flags you pass change). | Flag | Required | Description | | ------------------------------------------ | -------- | ------------------------------------------------------------------ | | `--suite ` | Yes | Eval suite name or ID | | `--project ` | No | Project name or ID (defaults to the most recently updated project) | | `--file ` | No | Suite-update JSON body (or `-` for stdin) | | `--json ` | No | Inline suite-update JSON (or `@file`, or `-`) | | `--name ` | No | Rename the suite | | `--description ` | No | Suite description | | `--server ` | No | Replace the suite's server selection (project server names) | | `--host ` | No | Replace host attachments (by name/ID) | | `--model ` | No | Execution model ID | | `--system-prompt ` | No | Execution system prompt | | `--temperature ` | No | Execution temperature | | `--min-accuracy ` | No | Minimum accuracy, 0–100 | | `--tool-call-order ` | No | Tool call order | | `--arguments ` | No | Argument matching | | `--extra-tool-calls ` | No | Allowed extra tool calls | | `--judge ` | No | Enable/disable LLM-as-judge grading | | `--judge-model ` | No | Judge model ID | ### `eval delete` Permanently delete an eval suite (and its cases and runs). | Flag | Required | Description | | ------------------------ | -------- | ------------------------------------------------------------------ | | `--suite ` | Yes | Eval suite name or ID | | `--project ` | No | Project name or ID (defaults to the most recently updated project) | ### `eval schedule` Enable or disable scheduled runs for a suite. | Flag | Required | Description | | ------------------------ | -------- | ------------------------------------------------------------------ | | `--suite ` | Yes | Eval suite name or ID | | `--project ` | No | Project name or ID (defaults to the most recently updated project) | | `--enable` | No | Enable scheduled runs | | `--disable` | No | Disable scheduled runs | | `--interval ` | No | Run interval in minutes (5–10080) | Pass either `--enable` or `--disable` (not both). ### `eval cases` subcommands #### `eval cases list` List a suite's test cases. | Flag | Required | Description | | ------------------------ | -------- | ------------------------------------------------------------------ | | `--suite ` | Yes | Eval suite name or ID | | `--project ` | No | Project name or ID (defaults to the most recently updated project) | #### `eval cases get` Show one test case. | Flag | Required | Description | | ------------------------ | -------- | ------------------------------------------------------------------ | | `--suite ` | Yes | Eval suite name or ID | | `--case ` | Yes | Eval case title or ID | | `--project ` | No | Project name or ID (defaults to the most recently updated project) | #### `eval cases create` Add a test case to a suite (definition via `--file`/`--json`). | Flag | Required | Description | | ------------------------ | -------- | ------------------------------------------------------------------ | | `--suite ` | Yes | Eval suite name or ID | | `--project ` | No | Project name or ID (defaults to the most recently updated project) | | `--file ` | No | Case JSON body (or `-` for stdin) | | `--json ` | No | Inline case JSON (or `@file`, or `-`) | | `--title ` | No | Case title (overrides the body) | #### `eval cases update` Edit a test case (definition via `--file`/`--json`). | Flag | Required | Description | | ------------------------ | -------- | ------------------------------------------------------------------ | | `--suite <id-or-name>` | Yes | Eval suite name or ID | | `--case <id-or-title>` | Yes | Eval case title or ID | | `--project <id-or-name>` | No | Project name or ID (defaults to the most recently updated project) | | `--file <path>` | No | Case JSON body (or `-` for stdin) | | `--json <json>` | No | Inline case JSON (or `@file`, or `-`) | | `--title <title>` | No | Rename the case | #### `eval cases delete` Permanently delete a test case. | Flag | Required | Description | | ------------------------ | -------- | ------------------------------------------------------------------ | | `--suite <id-or-name>` | Yes | Eval suite name or ID | | `--case <id-or-title>` | Yes | Eval case title or ID | | `--project <id-or-name>` | No | Project name or ID (defaults to the most recently updated project) | #### `eval cases generate` AI-generate test cases from the suite's tools (spends credits). | Flag | Required | Description | | --------------------------- | -------- | ------------------------------------------------------------------ | | `--suite <id-or-name>` | Yes | Eval suite name or ID | | `--project <id-or-name>` | No | Project name or ID (defaults to the most recently updated project) | | `--mode <normal\|negative>` | No | Generation mode (default `normal`) | | `--server <name...>` | No | Servers to discover tools from (default: suite's) | | `--case-model <id...>` | No | Execution model(s) for the generated cases | | `--simple <n>` | No | How many easy, single-tool cases | | `--multi-tool <n>` | No | How many medium, 2+ tool cases | | `--multi-turn <n>` | No | How many multi-turn follow-up cases | | `--complex <n>` | No | How many hard / cross-server cases | | `--negative <n>` | No | How many negative (no-tool) cases | | `--vary-user-styles` | No | Vary query phrasing across a realistic range of user styles | *** ## `mcp` command ### `mcp` Run MCPJam as an MCP server over stdio so MCP clients (Claude Desktop, Claude Code, Cursor, ...) can connect to, exercise, and debug other MCP servers. See [MCPJam as an MCP server](/cli/mcp-server) for the exposed tools and client setup. ```bash theme={null} npx -y @mcpjam/cli@latest mcp ``` The command takes no flags of its own. The global `--timeout <ms>` flag sets the default per-request timeout against target servers, and `--quiet` suppresses the startup notice on stderr. Stdout carries only JSON-RPC; never pipe other output into it. *** ## `telemetry` commands Telemetry commands inspect and configure anonymous CLI telemetry. They never emit telemetry events themselves. ### `telemetry status` Shows the effective telemetry state, install ID state, state file path, debug mode, and disable reason when disabled. This command does not create an install ID. ### `telemetry disable` Persistently disables anonymous CLI telemetry by writing `enabled: false` to the telemetry state file. If no install ID exists yet, this command does not create one. ### `telemetry enable` Persistently enables anonymous CLI telemetry. If no install ID exists yet, this command creates a random install UUID. *** ## `login` / `logout` / `whoami` commands These commands manage your MCPJam platform session. `login` opens a browser for OAuth and stores the session locally; `logout` removes it; `whoami` shows the account behind the current credentials. ### `login` | Flag | Default | Description | | ----------------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--api-url <url>` | `https://app.mcpjam.com/api/v1` | MCPJam API base URL. The value is persisted with the session so subsequent cloud commands target the same deployment without needing `--api-url` again. Must be a valid `http(s)` URL — an invalid value exits with code `2` before any network call. | | `--no-browser` | | Print the login URL to stderr instead of opening a browser. | The `MCPJAM_API_URL` environment variable is equivalent to `--api-url`. An invalid value in either source is a hard error (exit 2). **URL resolution order for cloud commands after login:** 1. Explicit `--api-url` flag 2. `MCPJAM_API_URL` environment variable 3. The `apiUrl` stored with the OAuth session (only when the stored login is the credential; `sk_` API keys do not inherit the stored URL) 4. Production default (`https://app.mcpjam.com/api/v1`) ### `logout` No additional flags. Removes the stored MCPJam session. ### `whoami` | Flag | Default | Description | | ----------------- | ------------------------------- | -------------------------------------------------- | | `--api-key <key>` | | MCPJam `sk_` API key (overrides `MCPJAM_API_KEY`). | | `--api-url <url>` | `https://app.mcpjam.com/api/v1` | MCPJam API base URL. | *** ## Exit codes | Code | Meaning | | ---- | ---------------------------------- | | `0` | Success / all checks passed | | `1` | Command ran but reported a failure | | `2` | Invalid arguments or configuration |