CLI reference

mcpscore [options] https://your-server.example/mcp
mcpscore [options] server.py
mcpscore [options] --stdio COMMAND [ARGS...]
mcpscore [options] --package npm:@scope/name

# 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.
`--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.
`--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.
`--sarif FILE`	off	Writes the failed rules as SARIF 2.1.0 to `FILE`, or to stdout with `-`. See 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.
`--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.

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.

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:

Audit finished. Final score: 91/108
...
Gate failed — --fail-under 90: score 91/108 (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 has the other causes.

Output streams

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

# 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'

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.

# 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

...
Audit finished. Final score: 91/108
SARIF written to mcpscore.sarif (13 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.

Example result

{
  "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.

Get started

Guides

Use in CI

Scoring

Reference

What to audit

Output

Rules and CI gates

Smoke checks

Authentication

Environment variables

Exit codes

Output streams

SARIF for GitHub code scanning

What’s next

Stability contract

Troubleshooting

​What to audit

​Output

​Rules and CI gates

​Smoke checks

​Authentication

​Environment variables

​Exit codes

​Output streams

​SARIF for GitHub code scanning

​What’s next

Stability contract

Troubleshooting

What to audit

Output

Rules and CI gates

Smoke checks

Authentication

Environment variables

Exit codes

Output streams

SARIF for GitHub code scanning

What’s next