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

# Stability contract

> What mcpscore keeps stable across releases, so your CI gates and report consumers keep working, and what moves on purpose.

Build on `rule_id`, the report schema, the CLI shape, and the exit codes.
Those change only in a major version. Messages, rule names, and the absolute
score move in minor releases, on purpose. This contract has been in force
since 1.1.0.

Here is a real `--json` report, trimmed to one result. The stable parts are
the ones your code should read:

```bash theme={null}
# Write a machine-readable report to a file
mcpscore https://mcp.deepwiki.com/mcp --json > report.json
```

```json theme={null}
{
  "schema_version": 1,
  "mcpscore_version": "1.31.0",
  "generated_at": "2026-11-04T12:22:46.618488+00:00",
  "target": "https://mcp.deepwiki.com/mcp",
  "transport": "streamable-http",
  "score": 153,
  "max_score": 171,
  "authenticated": false,
  "partial": false,
  "server_info": { "name": "DeepWiki", "version": "4.0.2" },
  "package": null,
  "summary": { "total": 53, "passed": 41, "failed": 12, "skipped": 76, ... },
  "results": [
    {
      "rule_id": "tools_annotations_present",
      "rule_name": "Tools - All tools should declare behavior annotations",
      "severity": "MEDIUM",
      "severity_value": 2,
      "passed": false,
      "message": "❌ Number of tools without behavior annotations: 3. ...",
      "details": {
        "issues": [
          {
            "entity_kind": "tool",
            "reason": "missing_behavior_annotation",
            "expected": "at least one behavior annotation reflecting actual effects",
            "entity_index": 0,
            "path": "/annotations"
          },
          ...
        ],
        "issues_total": 3,
        "issues_omitted": 0,
        "basis": "MCP 2025-11-25 Tools §Tool (annotations)"
      },
      "suggested_fix": "Declare behavior annotations that match the tool's actual effects. Set readOnlyHint to true only if the tool cannot change state."
    },
    ...
  ],
  "skipped_rules": [
    {
      "rule_id": "server_instructions_tool_references",
      "rule_name": "Server Info - Instructions reference listed tools",
      "reason": "not-applicable",
      "group_name": "server_info"
    },
    ...
  ],
  "spec": { "negotiated_version": "2025-11-25", "latest_version": "2026-07-28", "era": "dual-era", ... },
  "readiness": { "score": 43, "max_score": 45, "counted_in_main": true, "assessed": 18, "skipped": 3, "total": 21, ... }
}
```

Key a CI check or a dashboard on `rule_id`, `passed`, `severity_value`, and
the counts. Show `message`, `rule_name`, and `suggested_fix` to people. The
next sections say exactly which fields are which.

## Stable

### Rule identifiers

A `rule_id` such as `tools_annotations_present` is never renamed and never
reused for a different check. Rules are added in any release. A rule can be
retired and stop running, but its `rule_id` keeps its meaning forever. The
[rules reference](https://docs.mcpscore.dev/rules.md) lists retired rules too.

### Report schema

The `--json` report carries `schema_version`, currently `1`. Within a schema
version, existing fields keep their names, types, and meanings. New fields
appear in any release, so ignore fields you do not know. A removal or a type
change bumps `schema_version`.

| Field | Type | Meaning |
| - | - | - |
| `schema_version` | int | Report schema version |
| `mcpscore_version` | string | Engine that produced the report. Store it next to any score you keep |
| `generated_at` | string | ISO 8601 timestamp, UTC |
| `target` | string | What was audited, as given on the command line |
| `transport` | string or null | `stdio`, `streamable-http`, or `sse`. `null` for a package audit |
| `score`, `max_score` | int | Points earned and available on the main axis |
| `authenticated` | bool | An `Authorization` credential was sent. Never the credential itself |
| `partial` | bool | Only the observable surface of an auth-gated server was scored |
| `partial_reason` | string or null | Why the audit was partial |
| `incomplete_listings` | array | Catalogs whose paginated listing could not be fully collected |
| `listing_errors` | object | Sanitized errors keyed by catalog name. Values carry `outcome`, `page_index`, optional `error_code`, and optional bounded `issues`, `issues_total`, `issues_omitted` |
| `server_info` | object or null | `name` and `version` the server reported. `null` when identity was never observed |
| `package` | object or null | Always present. `null` for a server audit, an object for a [package audit](#package-audits) |
| `summary` | object | `total`, `passed`, `failed`, `skipped`, and `by_severity` counts |
| `results[]` | array | One entry per rule that ran: `rule_id`, `rule_name`, `severity`, `severity_value`, `passed`, `message`, `details`, and `suggested_fix` on failures that have [guidance](#failure-guidance) |
| `skipped_rules[]` | array | One entry per rule that did not run: `rule_id`, `rule_name`, `reason`, `group_name` |
| `spec` | object | `negotiated_version`, `session_protocol_version`, `latest_version`, `readiness_target`, `era`, `catalog_versions` |
| `readiness` | object | `score`, `max_score`, `counted_in_main`, `results[]`, plus the coverage counts `assessed`, `skipped`, `total` |
| `skills` | object or null | Facts about a server's skills that are not scored. `null` unless the server declares the Skills extension. See [skills facts](#skills-facts) |
| `smoke` | object | Present only when the run used `--smoke`. See [smoke results](#smoke-results) |
| `config` | object | Present only when a project configuration was applied. See [configuration](#configuration) |

`spec.catalog_versions` lists catalogs judged on a revision other than the
negotiated one, keyed by listing name. It is empty unless a legacy listing
failed and the stateless modern listing served it.

### Package audits

`package` is `null` for every server audit. When it is an object, the report
is a package audit. Its score comes from the packaging rules alone, a rule set
separate from server audits, so anything that compares or aggregates scores
must branch on this field.

| Field | Meaning |
| - | - |
| `registry`, `identifier` | `npm` or `pypi`, and the package name |
| `requested_version`, `resolved_version` | The pin you gave, and what the registry resolved it to |
| `outcome`, `error` | Whether the registry read succeeded, and why not |
| `repository_url`, `license`, `published_at`, `withdrawn` | The metadata the rules judged |
| `executed` | Always `false`. The package was read, never downloaded or run |

For a package audit, `transport` and `spec.negotiated_version` are both
`null`.

### Skills facts

`skills` reports what a host decides about, so mcpscore shows it without
scoring it:

| Field | Meaning |
| - | - |
| `skills_listed`, `listing_incomplete` | Skills in the listing, and whether pages were left unread |
| `skills_with_allowed_tools`, `skills_with_scripts` | Skills that request pre-approved tools, or bundle files under `scripts/` |
| `skills[]` | Up to 32 of those skills: `uri`, `allowed_tools` (`null` when it is not a string), `scripts` (up to 20), `scripts_total` |
| `openai_import` | OpenAI imports at most `skills_imported_at_most` skills and `scan_archive_limit_bytes` of archives per scan. `listed_bytes` sums the listed sizes. `fits` is `true` when the whole catalog would be imported even uncompressed, each skill within OpenAI's per-skill limits, and `false` when too many skills or a skill over its limits rule it out. It is `null` otherwise: the listing or a skill's sizes are incomplete, or only compression could bring the archives under the limit |

### Smoke results

`smoke` is absent unless the run used [`--smoke`](https://docs.mcpscore.dev/smoke-mode). Smoke results
never count in `score` or `max_score`. A smoke failure is reported through
exit code `4`.

| Field | Meaning |
| - | - |
| `executed` | `false` when no session existed to call tools on, with the explanation in `reason` |
| `call_all` | Whether `--call-all` was given |
| `summary` | `passed`, `failed`, `skipped` counts |
| `coverage` | `tools_called`: distinct tools the server answered at least one `tools/call` for. `tools_total`: distinct tools the checks looked at |
| `checks[]` | `check_id`, `tool_name` (`null` for server-level checks), `verdict` (`pass`, `fail`, `skip`), `message`, `details` |

A check whose call completed sets `details.called: true`. A check that
received a result also carries a bounded `details.response` with
`content_blocks`, `content_types`, `structured_content`, `is_error`, and
`first_text` capped at 80 code points. Do not require `details.response`.
`check_id` values are stable in the same way `rule_id`s are.

### Configuration

`config` is absent unless a `mcpscore.toml` or `[tool.mcpscore]` table was
applied ([configure rules](https://docs.mcpscore.dev/configure-rules.md)). When present, the score was
computed under that policy:

* Rules turned off did not run. They appear in `skipped_rules[]` with reason
  `disabled-by-config`, unless the engine could not have judged the rule
  anyway, in which case the canonical skip reason is kept.
* Re-ranked rules carry their configured severity in `results[]`, with the
  default in `details.severity_default`.
* A configured score is comparable only across runs with the same
  `config.sha256` and engine version. The badge and mcpscore.dev never apply
  a configuration.

| Field | Meaning |
| - | - |
| `source`, `sha256` | The file that was applied, and a digest of its bytes |
| `disabled` | Rule IDs turned off |
| `reranked` | Rule ID to `{"from": default, "to": configured}` severity names |
| `unknown` | Configured IDs this engine does not have. Warned about and ignored |
| `gate` | Present when `[gate]` is set: `fail_on` and the `failed` rule IDs that tripped it |

### CLI interface

The invocation shape is stable: `mcpscore <target>` with `--json`,
`--header`, `--token`, and the `MCPSCORE_TOKEN` environment variable. New
flags are added. Existing flags keep their meaning.

* `mcpscore --version` prints `mcpscore <version>` to stdout, exits `0`, and
  needs no target.
* `--json` writes exactly one JSON document to stdout. All logs go to stderr.
* `--sarif FILE` writes SARIF 2.1.0 with one `result` per failed rule, keyed
  by `ruleId` = `rule_id`. The severity-to-level mapping and the
  `primaryLocationLineHash` fingerprint (a hash of the rule and the target)
  keep their meaning, so code scanning alerts survive an upgrade.

| Exit code | Meaning |
| - | - |
| `0` | Audit completed. With no gate flags, this is the result whatever the score |
| `1` | Audit never attempted: usage error, or `--oauth` failed (timeout, refusal, registration or token-exchange failure) |
| `2` | Could not connect to the target, with no fallback available |
| `3` | Audit completed but `--fail-under`, `--fail-under-readiness`, or a configured `[gate]` was not met. A partial audit always fails `--fail-under` |
| `4` | Audit completed but a `--smoke` check failed. When a threshold also fails, `3` is returned |

For what to do about each code, see [troubleshooting](https://docs.mcpscore.dev/troubleshooting.md).

### Credentials

Header and token values are never logged and never written to the report.
The report records only the boolean `authenticated`. This is a permanent
commitment.

## Evolving by design

| What | How it moves | What to do |
| - | - | - |
| `score` and `max_score` | Most releases add rules, so both numbers change. A score is comparable only within one mcpscore version against one server | Store `mcpscore_version` with every score. Compare across versions by `rule_id`, not by total |
| `partial: true` | Fewer checks ran | Never compare with a full audit |
| `config` present | The run applied a project configuration | Compare only across runs with the same `config.sha256` |
| `readiness.counted_in_main: true` | A modern-lifecycle server's readiness points are inside the main score | A score threshold means something slightly different on either side of this flag |
| `message`, `details`, `rule_name`, severities, category groupings | Improved in any release | Show them to people. Never key logic on them |
| SARIF rule metadata (`shortDescription`, `fullDescription`, `helpUri`, `properties`) | Grows as rules gain citations and docs anchors move | Key on `ruleId` and the fingerprint, as GitHub does |
| Readiness rules | Target the newest revision, currently 2026-07-28. As adoption grows they move into the main axis, and new ones appear for the next revision | Their `rule_id`s follow the never-reused rule |

mcpscore grows its checks rather than freezing the number early. A calibrated
scoring frame will revisit this once the rule set settles. The
[methodology](https://docs.mcpscore.dev/methodology.md#scoring-across-spec-revisions) explains how rules
apply per spec revision.

## Versioning

mcpscore follows [SemVer](https://semver.org/). Breaking anything in the
Stable section needs a major version. Rule additions and score movement are
minor-version changes. Pre-releases (`bN`) can change anything.

## Failure guidance

A failed rule can carry two kinds of guidance: a repair hint in
`suggested_fix`, and structured evidence in `details.issues`. Neither changes
a verdict, an applicability decision, or a score weight.

### Repair hints: `suggested_fix`

| Property | Contract |
| - | - |
| Presence | Failures only. Absent on passes and on findings without authored guidance. Tolerate its absence |
| Length | Nonblank, at most 255 Unicode code points. In JavaScript, count with `Array.from(text).length`, not `text.length` |
| CLI | Printed as `Fix:` on stderr. JSON stdout stays one complete report |
| SARIF | Appended to the finding message after sanitizing, under SARIF's stricter URL privacy policy. It never invents source edits |

Hints cover tool, resource, resource-template, prompt, server-metadata,
capability, protocol, transport, auth and security, pagination,
catalog-stability, readiness, and package rules. A hint for optional metadata
or list-change advice says it is a quality recommendation in the message,
not a protocol mandate.

Requirement strength is not inferred from severity or from the presence of a
hint. Read the rule's `details.basis` and the revisions it applies to. A hint
is advice for that finding.

### Structured evidence: `details.issues`

Schema and catalog failures keep their existing detail keys and add a bounded
list of issues. Each issue names where the problem is and what was expected:

| Field | Meaning |
| - | - |
| `entity_kind` | What the issue is about: `tool`, `resource`, `resource_template`, `prompt`, `server`, `catalog`, or `response` for readiness probes |
| `entity_index` | Zero-based index in the collected, concatenated catalog. Absent for `server` and `catalog` issues |
| `path` | JSON Pointer relative to that item, using MCP wire field names, such as `/inputSchema/properties/query/description` |
| `reason`, `expected` | Why it failed, and the constraint it was checked against |
| `path_omitted` | `true` when the path was longer than 255 code points and left out |

At most 20 issues are included. `issues_total` counts every affected field or
occurrence, and `issues_omitted` counts those past the limit. Each tool
contributes its first failing predicate. Messages name the first affected
field, and the full bounded evidence stays in `details`.

> [accordion] Technical details: issue paths and catalog evidence
>
> * Prompt arguments and icons include their own indexes in the path.
> * Server metadata paths start at `/serverInfo`, `/instructions`, or
>   `/capabilities`, with no catalog index. An empty-tools finding uses
>   `/tools`, relative to the catalog result.
> * Stored paths keep their exact JSON Pointer characters, including newlines,
>   quotes, and backslashes. Only CLI rendering escapes them.
> * Issues leave out publisher names, URI values, image data, and arbitrary
>   schema values. Indexes still identify entries with missing or duplicate
>   names.
> * `issues_total` counts affected fields or occurrences, which can differ from
>   a legacy count of distinct names or duplicate identifiers.
> * Schema diagnostics explain the existing validator. They do not extend it to
>   complete JSON Schema conformance. A tool's optional output schema is checked
>   only when present.
> * Existing detail keys are kept for compatibility and are not covered by the
>   evidence bound.
> * An optional field with an invalid declared value still needs repair.
> * Header uniqueness groups annotations by tool name. Resolve duplicate tool
>   names before treating a collision across entries as an error within one
>   tool.
> * Server icons are checked for an `https://` or `data:` prefix only. A
>   declared `listChanged` flag does not prove that notifications work.
> * Catalog collection failures are recorded in the report's `listing_errors`,
>   and in `details.collection_error` when a declaration rule fails. Outcomes
>   are `invalid_response`, `timeout`, `rpc_error`, or `collection_error`.
>   Validation locations and expected types are kept, without raw response
>   values or exception messages.
> * Modern result objects with a missing or non-array `tools` field also get
>   sanitized field-shape diagnostics. The probe outcome stays unsupported.

> [accordion] Technical details: protocol and probe evidence
>
> * Failed protocol and probe checks keep their observations and can add
>   `details.expected` for the fields checked.
> * Human messages include observed error codes and statuses only when present.
>   Stdio messages leave out the HTTP status.
> * Cursor probes distinguish a returned page from an unexpected response,
>   rather than inferring success from a missing error code.
> * Audit context is recorded once: `transport` at report level, and
>   `spec.negotiated_version` and `spec.session_protocol_version` in the `spec`
>   block. `session_protocol_version` is `null` unless a legacy session was
>   established. Existing `target_version`, `spec`, and `basis` detail fields
>   keep the rule's revision and source.
> * Unavailable probes still skip. A hint never turns missing evidence into a
>   failure.
> * Readiness result-field issues use `entity_kind: "response"`, the
>   originating `probe_id`, and paths relative to the JSON-RPC `result`.
>   `missing_or_null` means the observation cannot distinguish omission from an
>   explicit null. `invalid_value` means a value was observed and failed the
>   existing predicate.
> * Readiness tool-schema issues use catalog indexes and paths relative to each
>   tool, with the same 20-issue and 255-code-point bounds. A network-reference
>   finding identifies the containing schema. It does not prove a fetch.
> * For readiness schema failures, `offending_tools` keeps its legacy shape,
>   keyed by name, with short problem labels and no values.
>   `offending_tool_indexes` maps each name to all affected catalog indexes,
>   including duplicate names. Unlike `issues`, this index mapping is complete.

> [accordion] Technical details: credential masking and message previews
>
> Evidence copies in rules and probes mask credentials:
>
> * `response_session_id` becomes `[redacted]`. Absence stays `null`.
> * URL userinfo is removed.
> * These query keys are masked: `access_token`, `refresh_token`, `id_token`,
>   `token`, `api_key`, `apikey`, `client_secret`, `password`, `secret`,
>   `authorization`, and `code`. Matching is case-insensitive after URL
>   decoding, and treats hyphens like underscores.
> * Every `scheme://` URL is matched case-insensitively, including PostgreSQL
>   and HTTP URLs, dictionary keys, and URLs inside challenge headers and
>   exception text.
> * Public query parameters, spelling, order, fragments, `WWW-Authenticate`
>   challenges, and diagnostic exception reasons stay available.
> * When masked dictionary keys collide, every entry is kept with a
>   deterministic ` [masked name N]` suffix. Literal keys are reserved first,
>   and summary maps with the same source names use the same aliases. These
>   aliases are report labels, not tool names. Use catalog indexes to identify
>   tools.
>
> Human messages show bounded, quoted previews of values:
>
> * A preview holds at most 60 source code points, with a visible truncation
>   marker. A value that is a single URL keeps up to 200. A list renders item
>   by item, at most 10 items, then a count.
> * Printable Unicode stays readable. Quotes, backslashes, and nonprinting
>   characters are escaped, so a rendered preview can be longer than the bound.
> * Messages can show server identity values on passes, and up to three
>   duplicate tool names on failures. Website URL values are not echoed in
>   passing messages.
> * Previews of resource and issuer identifiers, version lists, `Content-Type`
>   values, and schema-validator reasons appear after credential masking.
>   Validator previews appear only in the human message, never in structured
>   summaries.
> * The full values stay in the legacy detail keys. The preview is a display
>   bound, not secret redaction.
>
> These protections do not change the observations used for scoring, and they
> are not a general secret detector. Error text and public metadata can carry
> sensitive information outside these patterns. Review a report before you
> publish it.

> [accordion] Technical details: what a passing check proves
>
> * A passing PKCE finding establishes advertised `S256` support, not an
>   executed authorization flow.
> * An error-hygiene pass means no configured pattern was found in the sampled
>   response.
> * Catalog-stability passes compare two connections made with the same
>   authorization.
> * Modern-protocol hints keep valid legacy paths working. Readiness promotion
>   into the main score is unchanged by hints.
> * Authorization discovery follows the order a client uses: the challenge's
>   `resource_metadata` URL first, wherever it is hosted, then the
>   [well-known locations](https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization/authorization-server-discovery#protected-resource-metadata-discovery-requirements).
>   The metadata it finds must name the audited endpoint as its `resource`
>   ([RFC 9728 section 3.3](https://www.rfc-editor.org/rfc/rfc9728.html#section-3.3)).
> * From 2025-11-25 on, a 401 challenge without `resource_metadata` is not a
>   finding on its own: the server may publish at a well-known location
>   instead, and `auth_protected_resource_metadata` judges whether it does. On
>   2025-06-18 the parameter is required.
> * Issuer metadata is looked up in the
>   [MCP discovery order](https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization/authorization-server-discovery#authorization-server-metadata-discovery),
>   including path insertion for an issuer with a path. A document counts only
>   when its `issuer` is identical to the listed issuer; a difference in the
>   trailing slash alone is accepted and reported. A failure lists the
>   locations tried; it does not prove that no valid document exists elsewhere.
> * Discovery URLs that point a public server at loopback, link-local or private
>   addresses are reported, not fetched. Host names are resolved first. A
>   lookup that times out is not fetched either, and is reported as unreachable.

> [accordion] Technical details: package evidence
>
> * Package hints separate publisher metadata changes from consumer choices.
> * npm deprecation and PyPI yanking keep their registry-specific names and
>   the publisher's notice when available, in `details.withdrawal_reason`.
> * Notice previews allow 200 code points, so replacement URLs in the notice
>   stay useful. Masking and control-character escaping happen before display.
>   Longer notices are visibly truncated, and the full masked notice stays in
>   `details`.
> * Existing `yanked` detail values and verdicts are unchanged. Public values
>   use bounded quoted previews, and URL credentials are masked in messages and
>   details.
> * A missing license or repository URL describes the metadata. It says
>   nothing about legal permissions or whether the source exists elsewhere.
> * Package audits never run the package and cannot confirm its MCP behavior.

## What's next

> [card] [CLI reference](https://docs.mcpscore.dev/cli.md)
>
> Every flag and exit code, with defaults

> [card] [Scoring methodology](https://docs.mcpscore.dev/methodology.md)
>
> How the score is computed, and why it depends on the rule set


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