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
/mcpto/api/mcpand theresourcein 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_supportedfrom 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
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)
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"
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
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
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 |
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)