Configure rules

Some rules won’t apply to your server, and some matter more to you than their default weight says. A mcpscore.toml next to your code turns rules off and re-ranks the rest by rule_id, and the score you see in CI is the score under that policy. The badge and mcpscore.dev never read it. They always show the canonical score.

mcpscore.toml

[rules]
server_websiteurl_present = "off"   # we do not publish a website
server_title_present = "critical"    # our agent picks servers by title

[gate]
fail_on = "critical"   # any failed rule at or above CRITICAL fails the build

Config: mcpscore.toml — 1 rule off, 1 re-ranked, gate at CRITICAL
...
⏭️ Skipping rule 'server_websiteurl_present': disabled-by-config
...
Audit finished. Final score: 118/142 (mcpscore.toml: 1 rule off, 1 re-ranked, gate at CRITICAL)
Gate failed — [gate] fail_on = "critical": 1 failed rule at or above CRITICAL: server_title_present

The score line names the file, so a pasted number keeps its qualifier. The gate names the rule that failed the build.

Build the file one entry at a time

The steps below build that file against the one-tool server from smoke mode. With no configuration it scores 118/140, and two of its failed rules are server_websiteurl_present and server_title_present. Every rule_id is in the rules reference. Create mcpscore.toml in the directory you run mcpscore from, or anywhere above it inside the repository.

Step 1: Turn a rule off

mcpscore.toml

[rules]
server_websiteurl_present = "off"   # we do not publish a website

mcpscore --stdio uv run server.py

Config: mcpscore.toml — 1 rule off
...
⏭️ Skipping rule 'server_websiteurl_present': disabled-by-config
Audit finished. Final score: 118/139 (mcpscore.toml: 1 rule off)

The first line says which file was applied. The rule no longer runs, so its point leaves the maximum: 140 becomes 139. It appears in the report’s skipped_rules with reason disabled-by-config.

Step 2: Re-rank a rule

A severity name instead of off keeps the rule running and changes its weight. server_title_present is MEDIUM by default, worth 2 points. Make it critical, worth 5:

mcpscore.toml

[rules]
server_websiteurl_present = "off"   # we do not publish a website
server_title_present = "critical"    # our agent picks servers by title

Config: mcpscore.toml — 1 rule off, 1 re-ranked
...
Audit finished. Final score: 118/142 (mcpscore.toml: 1 rule off, 1 re-ranked)

The rule still fails, so the score stays at 118 and the maximum grows by 3. The weights are 1, 2, 3 and 5 points for low, medium, high and critical.

Step 3: Fail the build on it

Add a [gate] table. Any failed rule counted in the main score at or above fail_on exits with code 3:

mcpscore.toml

[rules]
server_websiteurl_present = "off"   # we do not publish a website
server_title_present = "critical"    # our agent picks servers by title

[gate]
fail_on = "critical"   # any failed rule at or above CRITICAL fails the build

Audit finished. Final score: 118/142 (mcpscore.toml: 1 rule off, 1 re-ranked, gate at CRITICAL)
Gate failed — [gate] fail_on = "critical": 1 failed rule at or above CRITICAL: server_title_present

The exit code is 3, the same code as --fail-under, so a CI step that already fails on a low score now fails on this rule too. Re-ranking in Step 2 is what put the rule over the line. A rule that is off never trips the gate.

Step 4: Fix the server and watch it pass

Give the server a title:

server.py

from mcp.server import MCPServer

mcp = MCPServer("Basic Server", title="Basic Server")

✅ Server title is present: "Basic Server" (presence checked only).
...
Audit finished. Final score: 123/142 (mcpscore.toml: 1 rule off, 1 re-ranked, gate at CRITICAL)

The exit code is 0. The rule your team cares most about now guards every change, and the website score still counts it at its default weight.

What each entry does

Entry	Effect
`rule_id = "off"`	The rule does not run and counts toward neither the score nor the maximum. It appears in `skipped_rules` with reason `disabled-by-config`, unless the engine could not have judged it anyway, in which case the canonical reason (`not-applicable`, `insufficient-data`) is kept
`rule_id = "low"` / `"medium"` / `"high"` / `"critical"`	The rule runs and counts at that severity, worth 1, 2, 3 or 5 points. The result records the rule’s own severity as `details.severity_default`
`[gate] fail_on = "high"`	Exit code `3` when any failed rule counted in the main score sits at or above that severity after re-ranking. Readiness rules count only when a modern-lifecycle server promotes them, matching `--fail-under`
`[smoke.filesystem]`	Configures the filesystem boundary smoke check. It runs only with `--smoke` and never changes the score
`[smoke.network]`	Configures the network boundary smoke check. It runs only with `--smoke` and never changes the score

Values are case-insensitive. A rule_id that mcpscore doesn’t know, including one it has retired, is warned about and ignored, so a file written for a newer release still works on an older one. Any other value is a usage error and exit code 1.

Where the file lives

mcpscore looks in this order and prints the file it used on the Config: line:

--config FILE, any path. A missing file is a usage error.
Otherwise the nearest configuration, walking up from the working directory. The walk stops at the repository root, the first directory that contains .git. In each directory a mcpscore.toml wins over a pyproject.toml with a [tool.mcpscore] table, and a nearer file wins over one further up.

A pyproject.toml takes the same entries under tool.mcpscore:

pyproject.toml

[tool.mcpscore.rules]
server_websiteurl_present = "off"

[tool.mcpscore.gate]
fail_on = "high"

Config: pyproject.toml — 1 rule off, gate at HIGH

--no-config ignores all of it. That is how you reproduce the canonical number inside a configured repository:

mcpscore --no-config --stdio uv run server.py

Audit finished. Final score: 118/140

What it changes, and what it doesn’t

A configuration changes the score for the run that used it. It does not touch the badge or the report on mcpscore.dev, which only show audits run by the website itself, with every rule at its default weight. Two teams with different files get different numbers for the same server. Compare configured scores only across runs with the same config.sha256, which the report carries. In the JSON report the applied configuration is a config block:

"config": {
  "source": "mcpscore.toml",
  "sha256": "b17a4a83f436…",
  "disabled": ["server_websiteurl_present"],
  "reranked": {"server_title_present": {"from": "MEDIUM", "to": "CRITICAL"}},
  "unknown": [],
  "gate": {"fail_on": "CRITICAL", "failed": ["server_title_present"]}
}

The GitHub Action picks the file up from your checkout, so min-score gates the configured score, the PR comment carries the same qualifier, and a [gate] failure fails the job with the rule named.

When it fails

Usage error: mcpscore.toml: rule 'server_websiteurl_present' has value 'skip'; expected off, low, medium, high, or critical (exit 1)

Cause: an unsupported value. off is the one spelling.
Fix: use off or a severity name.

Config: unknown rule 'server_titel_present'; ignored

Cause: a rule_id this release doesn’t have, or a typo.
Fix: check the id in the rules reference.

Config: rule 'readiness_2026_origin_validation' was retired in mcpscore 1.20.0; ignored

Cause: the rule was removed from the engine. The retired-rules table in the rules reference says why, and names the replacement when there is one.
Fix: delete the line.

Usage error: missing.toml: cannot read config file: No such file or directory (exit 1)

Cause: --config points at a file that does not exist.
Fix: correct the path, or drop --config and let discovery find the file.

The badge still shows the old score after you turned rules off

Cause: the badge is canonical by design and never applies a configuration.
Fix: none needed. Your CI number and the badge answer different questions.

Recap

Turn a rule off with rule_id = "off".
Re-rank a rule with a severity name.
Fail the build with [gate] fail_on.
Fix the server, and the same file keeps guarding it.

What’s next

Rules reference

Every rule_id you can turn off or re-rank

GitHub Action

Gate pull requests on the configured score

Stability contract

The config report block, field by field

Scoring methodology

What the default weights mean before you change them

Get started

Guides

Use in CI

Scoring

Reference

Build the file one entry at a time

Step 1: Turn a rule off

Step 2: Re-rank a rule

Step 3: Fail the build on it

Step 4: Fix the server and watch it pass

What each entry does

Where the file lives

What it changes, and what it doesn’t

When it fails

Recap

What’s next

Rules reference

GitHub Action

Stability contract

Scoring methodology

​Build the file one entry at a time

​Step 1: Turn a rule off

​Step 2: Re-rank a rule

​Step 3: Fail the build on it

​Step 4: Fix the server and watch it pass

​What each entry does

​Where the file lives

​What it changes, and what it doesn’t

​When it fails

​Recap

​What’s next

Rules reference

GitHub Action

Stability contract

Scoring methodology

Build the file one entry at a time

Step 1: Turn a rule off

Step 2: Re-rank a rule

Step 3: Fail the build on it

Step 4: Fix the server and watch it pass

What each entry does

Where the file lives

What it changes, and what it doesn’t

When it fails

Recap

What’s next