> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mcpscore.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI reference

> Every mcpscore flag, environment variable, and exit code in one place.

```bash theme={null}
mcpscore [options] https://your-server.example/mcp
mcpscore [options] server.py
mcpscore [options] --stdio COMMAND [ARGS...]
mcpscore [options] --package npm:@scope/name
```

```bash theme={null}
# Audit a remote server
mcpscore https://mcp.deepwiki.com/mcp

# Audit a local server written in any language
mcpscore --stdio node build/index.js

# Fail a CI job when the score drops below 80%, and keep the JSON report
mcpscore https://your-server.example/mcp --fail-under 80 --json > report.json
```

`mcpscore --help` prints the same flags, grouped the same way as the tables below.

## What to audit

Give exactly one of these.

| Flag | Example | What it does |
| - | - | - |
| `target` | `https://your-server.example/mcp`, `server.py`, `server.js` | A URL is tried over Streamable HTTP, then SSE. A `.py` file runs under mcpscore's own interpreter; a `.js` file runs under `node`. |
| `--stdio COMMAND` | `--stdio uv run server.py`, `--stdio java -jar server.jar` | Starts the server with this command and audits it over stdio. Takes the rest of the command line, so every mcpscore option goes before it. Runs without a shell, so a script needs its interpreter. See [local servers](https://docs.mcpscore.dev/local-servers.md). |
| `--package COORDINATE` | `npm:@scope/name`, `npm:name@1.2.3`, `pypi:name==1.2.3` | Scores how a package is published, from registry metadata only. The package is never downloaded or run. Not comparable to a server score. See [package audits](https://docs.mcpscore.dev/package-audits.md). |
| `--env NAME=VALUE` | `--env LOG_LEVEL=debug` | Sets a variable for the `--stdio` server. Repeatable. The value is visible in shell history and the process list: plain config only. |
| `--env NAME` | `API_KEY=... mcpscore --env API_KEY --stdio ...` | Copies `NAME` from mcpscore's own environment. The form for secrets: the value never appears on a command line or in the report. |

Server stderr appears in the output prefixed with `server stderr:`, except
when a `.py` target fails on a missing module: mcpscore then prints the
command to run instead, and `-v` shows the stderr. The
sessionless probes start the server again for their own requests; those
extra processes stay silent.

## Output

| Flag | Default | What it does |
| - | - | - |
| `--json` | off | Writes the full report as one JSON document to stdout. Logs stay on stderr. Fields are in the [stability contract](https://docs.mcpscore.dev/stability.md#report-schema). |
| `--sarif FILE` | off | Writes the failed rules as SARIF 2.1.0 to `FILE`, or to stdout with `-`. See [SARIF for GitHub code scanning](#sarif-for-github-code-scanning). |
| `-v`, `--verbose` | off | Also logs every HTTP request, each failed probe, and the traceback behind a connection error. Everything goes to stderr, so `--json` output is unchanged. |
| `--version` | | Prints `mcpscore <version>` to stdout and exits `0`. Safe to parse. |

## Rules and CI gates

| Flag | Default | What it does |
| - | - | - |
| `--config FILE` | nearest `mcpscore.toml` or `[tool.mcpscore]` up to the repository root | Turns rules off, changes their severity, and sets a `[gate] fail_on` severity that exits `3`. Changes this run's score only; mcpscore.dev and the badge never apply it. See [configure rules](https://docs.mcpscore.dev/configure-rules.md). |
| `--no-config` | off | Ignores any configuration file. Standard rules and weights. |
| `--fail-under PCT` | none | Exits `3` when the score as a rounded percentage is below `PCT` (0 to 100). A partial audit always fails it. |
| `--fail-under-readiness PCT` | none | Exits `3` when the readiness percentage for the latest spec revision is below `PCT`. Skipped when readiness was not assessed. |

## Smoke checks

These flags call the server's tools. See [smoke mode](https://docs.mcpscore.dev/smoke-mode.md).

| Flag | Default | What it does |
| - | - | - |
| `--smoke` | off | After the audit, calls tools annotated `readOnlyHint: true` and checks output schemas, invalid-argument rejection, and unknown-tool rejection. Never changes the score. A failed check exits `4`. Needs a live session: skipped on partial and modern-only audits, refused with `--package`. |
| `--call-all` | off | With `--smoke`, calls every tool, including ones that write, delete, or send. Refused without `--smoke`. |

## Authentication

For URL targets. See [authenticated servers](https://docs.mcpscore.dev/authenticated-servers.md).

| Flag | Default | What it does |
| - | - | - |
| `--header 'Name: Value'` | | Sends an extra HTTP header. Repeatable. Values are never logged or reported. |
| `--token TOKEN` | `$MCPSCORE_TOKEN` | Shorthand for `--header "Authorization: Bearer TOKEN"`. An explicit `Authorization` header wins. |
| `--oauth` | off | Runs the server's OAuth flow in your browser (authorization code + PKCE). The token is kept in memory only. Needs dynamic client registration unless `--client-id` is given. Refused when a token is already set. |
| `--client-id ID` | | A pre-registered OAuth client for `--oauth` (GitHub's authorization server needs one). The app must allow `http://127.0.0.1:<port>/callback`. |
| `--callback-port PORT` | any free port | Fixes the loopback port of the `--oauth` redirect, for authorization servers that require the exact registered URI. |

Only an `Authorization` credential marks the report `authenticated: true`.
Other headers are sent and make no such claim.

## Environment variables

| Variable | Used by | Meaning |
| - | - | - |
| `MCPSCORE_TOKEN` | `--token` | Bearer token for auth-gated servers. The CI form: the value never appears on a command line. |

## Exit codes

| Code | Meaning | In CI |
| - | - | - |
| `0` | The audit completed and every gate that was set passed | Green |
| `1` | The audit never ran: a usage error, an unwritable `--sarif` file, or a failed `--oauth` sign-in | Fix the invocation |
| `2` | Could not connect to the server, or could not read the package registry | Fix the target or the network |
| `3` | The audit completed but `--fail-under`, `--fail-under-readiness`, or a `[gate]` was not met | The server needs work |
| `4` | The audit completed but a `--smoke` check failed. When a threshold gate also fails, `3` wins | The tools are broken |

Without a gate flag or a configured `[gate]`, a completed audit exits `0`
whatever the score. A failing gate names itself on the last line:

```text theme={null}
Audit finished. Final score: 96/114
...
Gate failed — --fail-under 90: score 96/114 (84%) is below the required 90%
```

A `2` that says the URL was redirected means mcpscore follows a redirect only
within the endpoint's origin and with the request unchanged. Audit the URL
the message names. [Troubleshooting](https://docs.mcpscore.dev/troubleshooting.md) has the other causes.

## Output streams

Human-readable output goes to stderr. With `--json`, stdout carries the
report and nothing else.

```bash theme={null}
# Every failed rule id, one per line
mcpscore https://mcp.deepwiki.com/mcp --json 2>/dev/null \
  | jq -r '.results[] | select(.passed | not) | .rule_id'
```

```text theme={null}
protocol_version_latest
server_title_present
server_websiteurl_present
server_icons_present
security_origin_validation
tools_title_present_in_all
...
```

### SARIF for GitHub code scanning

`--sarif` writes the failed rules in SARIF 2.1.0, the format GitHub's
Security tab reads. Upload the file and each failed rule becomes a code
scanning alert. The upload workflow is in the
[GitHub Action guide](https://docs.mcpscore.dev/github-action.md#send-findings-to-code-scanning).

```bash theme={null}
# The findings as a file for upload-sarif; the JSON report still goes to stdout
mcpscore https://mcp.deepwiki.com/mcp --json --sarif mcpscore.sarif > report.json
```

```text theme={null}
...
Audit finished. Final score: 96/114
SARIF written to mcpscore.sarif (15 findings)
```

| mcpscore severity | SARIF `level` | Security tab |
| - | - | - |
| `CRITICAL`, `HIGH` | `error` | Error |
| `MEDIUM` | `warning` | Warning |
| `LOW` | `note` | Note |
| Readiness rule not counted in the score | `note` | Note, whatever its severity |

| Property | Value |
| - | - |
| Results | One per failed rule. Passed and skipped rules are left out; `--json` is the full record. |
| `security-severity` | Set on Security & Auth rules, so they sort into the tab's critical, high, medium, and low bands. |
| `partialFingerprints` | Hashed from the rule and the shown target, so a re-upload updates the alert instead of opening a second one. |
| Location | A repository-relative path standing for the target, at line 1: host and path for a URL, `npm/name` for a package, the file for a local server. A local server's file is real, so GitHub can annotate line 1 when a pull request changes it. URL, package, and `--stdio` targets are synthetic paths and show only in the Security tab. |
| Target shown | A URL's scheme, host, port, and path; a `--stdio` command's program name; a local path; a package coordinate. Never a URL's userinfo, query, or fragment, a command's arguments, or rule `details`. |
| `--sarif -` | Writes to stdout. Combined with `--json`, exits `1` before the audit runs. |

> [accordion] Example result
>
> ```json theme={null}
> {
>   "ruleId": "protocol_version_latest",
>   "level": "warning",
>   "message": {
>     "text": "❌ Not using the latest protocol version: negotiated \"2025-11-25\", latest is '2026-07-28', and no stateless-lifecycle support was observed.\nSuggested fix: Implement the latest revision on the negotiated path or expose modern per-request lifecycle support. ..."
>   },
>   "locations": [{ "physicalLocation": { "artifactLocation": { "uri": "mcp.deepwiki.com/mcp" }, "region": { "startLine": 1, "startColumn": 1, "endLine": 1, "endColumn": 1 } } }],
>   "partialFingerprints": { "primaryLocationLineHash": "f1dcb75c967781b90dfa2a3e693e639b" },
>   "properties": { "severity": "MEDIUM", "severity_value": 2, "readiness": false, "counted_in_score": true }
> }
> ```

A SARIF file is read by everyone who can see the repository's alerts. Keep
credentials in `--token`, `--header`, or `--env NAME`, never in a URL path or
a program name.

## What's next

> [card] [Stability contract](https://docs.mcpscore.dev/stability.md)
>
> Which flags, fields, and exit codes stay stable across releases

> [card] [Troubleshooting](https://docs.mcpscore.dev/troubleshooting.md)
>
> Exit codes, connection failures, and partial audits


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.