Gate your MCP deploy in GitHub Actions

Check whether your endpoint is ready for Claude, ChatGPT, Cursor, VS Code, Claude Code and Codex, and whether this deploy breaks agents holding the previous tool list.

Copy this workflow

Create .github/workflows/mcp-gate.yml in your server repository. Deploy a reachable preview endpoint first, then replace the example URL.

name: MCP release gate
on: [pull_request, workflow_dispatch]
permissions:
  contents: read
  pull-requests: write
jobs:
  gate:
    runs-on: ubuntu-latest
    steps:
      - uses: integry/mcptest@v1
        with:
          endpoints: https://mcp.example.com/mcp
          baseline: none
          fail-on: blocked
          comment: 'true'
      - uses: actions/upload-artifact@v7
        if: always()
        with:
          name: mcptest-reports
          path: mcptest-reports/

The maintainer creates v1 when publishing. Until then use a reviewed commit SHA; pin a full SHA for reproducible production gates. The action sets up Node 22 and installs itself.

Compare with the last release

Start with baseline: none. Then use baseline: published to compare with the latest published report for the same endpoint, or supply a previous release JSON path. Missing baselines fail closed. Only publish from trusted release jobs if published history should represent the last release.

Set publish: true to make the redacted report public and include a permalink. Publishing is off by default. Use secret environment variable names in bearer-token or api-key, never literal credentials.

Example PR comment

This illustrative comment shows a removed contract blocking a deploy despite compatible client profiles. The action also links individual findings to reference sections.

## mcptest: blocked — gate failed

| Client | Compatibility |
| --- | --- |
| claude-ai | compatible-with-caveats |
| chatgpt | compatible |
| cursor | compatible |
| codex-cli | compatible |

Changes: 1 breaking, 1 safe

- **search** (breaking): Required input "filter" added.
- **lookup** (safe): Tool added.

Browser CORS and interactive OAuth remain unverified in headless CI.
Output schemas and annotations were not recorded in both snapshots.

Full report: a public mcptest.io/r permalink appears when publishing is enabled.

Grant pull-requests: write to update a single sticky PR comment. Fork PRs without permission skip commenting and retain their job summary and artifacts.

Run both readiness and conformance

The official MCP conformance suite tests against the specification. Run it alongside mcptest for spec checks. mcptest adds client-profile verdicts, OAuth evidence, breaking-change classification and optional session resilience. It does not launch client applications, prove browser CORS from Node, or certify conformance.

Read the CI guide for secrets, required clients, baseline limitations and rollout advice. Action reference lists every input and output.