DEV Community

Manoj Kumar
Manoj Kumar

Posted on

Fail your CI when your remote MCP server's OAuth breaks

Your remote MCP server worked yesterday. Today Claude says it "couldn't connect", and nothing in your test suite went red.

That's the normal way OAuth breaks on an MCP server. The tools still work. Your unit tests still pass, because they call the tools with a token they already have. What broke is the discovery chain a real client walks before it has a token: the 401 challenge, the protected resource metadata, the authorization server metadata, PKCE, client registration, CORS. None of that is on the path your tests take.

Last time I introduced mcp-auth-check, a CLI that walks that chain the way a client does. This post is about running it on every push, so the break shows up in a pull request instead of a user's bug report.

Why auth regressions slip through

The usual causes are boring:

  • Someone moves the server from /mcp to /api/mcp and the resource in your metadata still says /mcp.
  • A preview or staging deploy gets a new hostname, but the metadata has the production URL baked in.
  • An auth library upgrade drops code_challenge_methods_supported from the metadata. MCP clients must refuse to continue without PKCE S256, so they do.
  • A middleware refactor stops answering OPTIONS, and browser clients like MCP Inspector get blocked by CORS.

Each one is a one-line config change. Each one is invisible until a client tries to connect.

The 5-line workflow

- uses: manoj07ar/mcp-auth-check@v1
  id: auth
  with:
    url: https://staging.example.com/mcp
    fail-on: fail
Enter fullscreen mode Exit fullscreen mode

That's it. The action runs on the runner's own Node 24 from prebuilt files, so there's no npm install step. It sends an unauthenticated initialize, follows the metadata, and checks each link. It never signs in or sends credentials.

Here's what that step printed when I pointed it at the repo's deliberately broken mock server:

9 passed, 3 warnings, 2 failed, 1 skipped
Result: FAILED
::error title=mcp-auth-check: PRM resource matches the MCP URL::https://other.example.com/mcp does not match http://127.0.0.1:8799/mcp
::error title=mcp-auth-check: PKCE S256 advertised::code_challenge_methods_supported is missing; MCP clients MUST refuse to proceed without it
::error::mcp-auth-check: 2 failed, 3 warnings (fail-on: fail)
Enter fullscreen mode Exit fullscreen mode

Exit code 1, so the job goes red. Each ::error line becomes an annotation on the run, and each warning becomes a yellow one. Against the compliant mock, the same step printed 15 passed, 0 warnings, 0 failed, 1 skipped and exited 0. The skip is Dynamic Client Registration, which only runs if you opt in with extra-args: --dcr, because it creates a throwaway client on your server. With --dcr it came out at 16 passed, 0 skipped.

fail-on: warn vs fail

Checks come back as pass, warn, fail or skip. A fail means real clients will refuse to connect, for example a wrong resource or no PKCE. A warn means some clients will struggle, for example no CORS on the MCP endpoint or no way to register a client.

fail-on: fail (the default) only fails the step on failures. fail-on: warn fails on warnings too. I ran both against a mock that's correct apart from CORS:

fail-on Counts Exit ok output
fail 13 passed, 1 warning, 0 failed, 1 skipped 0 true
warn 13 passed, 1 warning, 0 failed, 1 skipped 1 false

Same server, same counts. Only the bar is different. I'd start with fail on a server that's already live, fix the warnings, then switch to warn so they can't come back.

Using the outputs and the JSON report

The step sets pass, warn, fail, skip, ok and result-json. For the broken mock they came out as 9, 3, 2, 1, false, plus the path to the report.

- if: always()
  run: echo "${{ steps.auth.outputs.fail }} failed, ${{ steps.auth.outputs.warn }} warnings"
Enter fullscreen mode Exit fullscreen mode

The JSON report holds every check with an id, status, detail and spec link. Set json-output: mcp-auth-report.json to write it into the workspace, then upload it as an artifact or filter it. This is the real output of a jq filter on the broken mock's report:

$ jq -r '.results[] | select(.status=="fail") | "\(.id): \(.detail)"' mcp-auth-report.json
prm.resource: https://other.example.com/mcp does not match http://127.0.0.1:8799/mcp
as.pkce_s256: code_challenge_methods_supported is missing; MCP clients MUST refuse to proceed without it
Enter fullscreen mode Exit fullscreen mode

That's enough to post a PR comment, open an issue, or feed a dashboard, using whatever tooling you already have.

Running against a preview deploy

The most useful place for this is the preview URL. That's where the "metadata still says production" bug shows up. If your host reports deployments back to GitHub (Vercel does, for example), trigger on deployment_status:

on: deployment_status

jobs:
  mcp-auth:
    if: github.event.deployment_status.state == 'success'
    runs-on: ubuntu-latest
    steps:
      - uses: manoj07ar/mcp-auth-check@v1
        with:
          url: ${{ github.event.deployment_status.environment_url }}/mcp
          fail-on: warn
          extra-args: --timeout 20000
Enter fullscreen mode Exit fullscreen mode

If preview URLs sit behind your host's own login wall, the check will see that wall instead of your server. Use a bypass your host supports, or run against staging. A weekly schedule run against production is also worth adding. It catches config drift that no commit caused.

What the job summary looks like

The action also writes a Markdown table to the run's summary page. This is the top of the one for the broken mock (detail column trimmed here for width):

## mcp-auth-check ❌ failed

Target: `http://127.0.0.1:8799/mcp`
**9** passed, **3** warnings, **2** failed, **1** skipped (fail-on: `fail`)

| Status  | Group                         | Check                                      |
|---------|-------------------------------|--------------------------------------------|
| ⚠️ WARN | unauthenticated               | WWW-Authenticate has resource_metadata     |
| ❌ FAIL | protected-resource-metadata   | PRM resource matches the MCP URL           |
| ❌ FAIL | authorization-server-metadata | PKCE S256 advertised                       |
| ⚠️ WARN | authorization-server-metadata | Client registration available (DCR / CIMD) |
| ⚠️ WARN | cors                          | CORS preflight on MCP endpoint             |
Enter fullscreen mode Exit fullscreen mode

The full table lists all 15 checks, passes included. Each check name links to the part of the spec it tests, so whoever opens the failed run can see what's wrong and where the rule comes from without running anything locally.

Limits

It checks discovery and metadata, not the sign-in itself. It won't test your consent screen, token exchange or refresh rotation. For those you still want an end-to-end test that plays the client. But most "couldn't connect" reports start in the part this does check, and now that part runs on every push.

Code, issues and the GitHub Action: https://github.com/manoj07ar/mcp-auth-check


If you'd rather start from a server that passes every check, my Remote MCP Connector Kit is here.

Top comments (0)