GitHub Action

Run mcpscore in CI with the official mcpscore-action. It audits your MCP server on every pull request, fails the build if quality drops below a threshold you set, and posts the report as a pull-request comment.

- uses: mcp-box/mcpscore-action@v1
  with:
    target: https://your-server.example/mcp
    min-score: 80

Why run it in CI

A local mcpscore check is a snapshot; CI makes quality a standard you can’t regress past:

Catch regressions before merge. A refactor that drops a tool description or breaks a schema shows up as a failing check on the PR — not in production, inside someone else’s agent.
A visible quality bar. The score and its trend live on the PR, so reviewers and contributors see the impact of a change without running anything.
Readiness tracking for the latest spec. The action reports the separate readiness score for the current 2026-07-28 MCP revision, so you know where you stand as clients adopt it.
Deterministic and fast. No API keys, no LLM calls — the same server state always produces the same result, in seconds.

Quick start

Gate a pull request on quality. The pull-requests: write permission lets the action post its comment.

name: MCP quality
on: [pull_request]

jobs:
  audit:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
    steps:
      - uses: mcp-box/mcpscore-action@v1
        with:
          target: https://your-server.example/mcp
          min-score: 80

pull-requests: write is the permission GitHub’s token uses to comment on a pull request — the same scope every PR-comment action uses. (The comment goes through the issue-comments API, but the token’s pull-requests scope is what authorizes it for a PR.)

On pull requests from a fork, GitHub gives the workflow token read-only access, so the comment can’t be posted. The audit and the score gate still run normally — only the comment is skipped. To comment on fork PRs, run the audit in a pull_request_target workflow, and review the security implications of doing so first.

Audit a local server from the repo

For a server that lives in the repository, check out the code and point target at the entry file:

- uses: actions/checkout@v4
- uses: mcp-box/mcpscore-action@v1
  with:
    target: ./server.py
    min-score: 85

Audit an auth-gated server

Store the credential as an Actions secret and export it as MCPSCORE_TOKEN — the CLI picks it up automatically and the value never appears in logs or in the report:

- uses: mcp-box/mcpscore-action@v1
  with:
    target: https://your-server.example/mcp
    min-score: 80
  env:
    MCPSCORE_TOKEN: ${{ secrets.MCPSCORE_TOKEN }}

For API-key servers, pass a header through args instead — see Authenticated Servers for all the flavors:

- uses: mcp-box/mcpscore-action@v1
  with:
    target: https://your-server.example/mcp
    args: --header 'X-Api-Key: ${{ secrets.MCP_API_KEY }}'

Without a credential, an auth-gated server gets a partial audit of its observable surface (auth posture, TLS, transport). Partial scores cover fewer checks and are not comparable to full-audit scores — calibrate min-score against whichever kind of audit the workflow actually runs.

Also require readiness for the 2026-07-28 spec

- uses: mcp-box/mcpscore-action@v1
  with:
    target: https://your-server.example/mcp
    min-score: 85
    min-readiness: 50   # fail if less than 50% ready for MCP 2026-07-28

The readiness gate only applies when the server was actually assessed for readiness. HTTP and stdio servers are both probed; if the modern lifecycle could not be observed at all, min-readiness is skipped rather than failing the build.

Use the outputs in later steps

Every number is exposed as a step output:

- id: mcp
  uses: mcp-box/mcpscore-action@v1
  with:
    target: https://your-server.example/mcp
- run: echo "Scored ${{ steps.mcp.outputs.percentage }}% (era ${{ steps.mcp.outputs.era }})"

What you get on the PR

The action posts one comment and updates it in place on every re-run — no comment spam. It contains the overall score, a pass/fail breakdown by severity, the negotiated spec version and era, the separate readiness score, and a collapsible list of every failed check by rule_id (so a fix is one lookup in the rules reference away). The same report is written to the run’s job summary.

Inputs

Input	Default	Description
`target`	— (required)	MCP server URL, or a local `.py` / `.js` path
`version`	latest	mcpscore version to run (e.g. `1.9.0`)
`min-score`	none	Fail if the main score percentage (0–100) is below this
`min-readiness`	none	Fail if the readiness percentage (0–100) is below this
`comment`	`true`	Post / update the report comment on the pull request
`args`	—	Extra arguments passed to the mcpscore CLI
`report-path`	`mcpscore-report.json`	Where the JSON report is written
`github-token`	`github.token`	Token for the PR comment (needs `pull-requests: write`)

Outputs

Output	Description
`score` / `max-score` / `percentage`	Main score
`readiness-score` / `readiness-max` / `readiness-percentage`	Readiness score for the latest spec revision
`era`	`legacy`, `modern`, or `dual-era`
`negotiated-version`	Spec version the server negotiated

Pinning the version

@v1 follows the latest v1 release, so you get fixes automatically. For fully reproducible runs, pin the action to a commit SHA and pin version to a specific mcpscore release:

- uses: mcp-box/mcpscore-action@<commit-sha>  # v1.x.y
  with:
    target: https://your-server.example/mcp
    version: "1.9.0"
    min-score: 80

Scoring Methodology

How the score works, and why the readiness axis is separate

Rules Reference

Every rule the action can flag, by rule_id

Action source

mcp-box/mcpscore-action on GitHub

mcpscore CLI

Run the same audit locally

Get Started

Guides

Use in CI

Scoring

Why run it in CI

Quick start

Audit a local server from the repo

Audit an auth-gated server

Also require readiness for the 2026-07-28 spec

Use the outputs in later steps

What you get on the PR

Inputs

Outputs

Pinning the version

See also

Scoring Methodology

Rules Reference

Action source

mcpscore CLI

​Why run it in CI

​Quick start

​Audit a local server from the repo

​Audit an auth-gated server

​Also require readiness for the 2026-07-28 spec

​Use the outputs in later steps

​What you get on the PR

​Inputs

​Outputs

​Pinning the version

​See also

Scoring Methodology

Rules Reference

Action source

mcpscore CLI

Why run it in CI

Quick start

Audit a local server from the repo

Audit an auth-gated server

Also require readiness for the 2026-07-28 spec

Use the outputs in later steps

What you get on the PR

Inputs

Outputs

Pinning the version

See also