mcp-authprobe

mcp-authprobe

Active authorization testing for remote MCP servers you own.

Passive scanners read what a remote Model Context Protocol server *announces*: its OAuth metadata, its TLS setup, its tool descriptions. Some properties can only be confirmed by actually exercising the authorization server: does it really rotate refresh tokens, does it really refuse a redirect URI it never registered, does it enforce PKCE, does it accept a token meant for another server, does it slow down repeated failures?

mcp-authprobe runs those active checks, against servers whose ownership you have proven, and reports the results as JSON, SARIF and Markdown.

19 checks, field-tested against a certified OpenID provider: OAuth discovery, refresh token rotation and replay, redirect URI strictness, PKCE enforcement, single-use codes, token audience, Origin validation, tokens in URLs, session IDs used as credentials, CORS, throttling and consent CSRF (in a real browser). It works as a CLI with an interactive login, as an MCP server so an AI assistant can run the audit, and as a GitHub Action. A deliberately vulnerable lab lets you try everything in a minute.

Only test servers you own or are explicitly authorized to test. Active checks change state on the target. The tool enforces an ownership proof before running them, but responsibility stays with the operator.

Contents

• Field-tested
• Why another scanner?
• Install
• Try it in a minute: the lab
• Quick start
• Ownership proof
• Refresh token checks
• Interactive login
• Redirect URI checks
• Throttling check
• Consent CSRF check
• Use it from an MCP client
• What it checks
• Combine with mcp-posture
• Reports and exit codes
• GitHub Action
• Safety of the scanner
• Roadmap
• Development
• Contributing and security

Field-tested

Besides its own test suite and lab, mcp-authprobe was run against real authorization stacks before each release:

• node-oidc-provider (an OpenID Certified authorization server) with dynamic registration, resource indicators and JWT access tokens, in front of an MCP server built with the official TypeScript SDK that validates the token audience and the Origin header. Every check that can be judged from outside passed; MAP-THR01 failed, as expected, since that provider leaves rate limiting to the deployment; and its consent page, protected by a per-flow identifier instead of an anti-CSRF field, is reported as inconclusive with the reason.
• The MCP TypeScript SDK's OAuth example server, a demonstration that is not meant for production. The results matched its code: redirect_uri not bound to the code, no Origin validation, unsafe redirect URIs accepted at registration, no refresh tokens, and crashes reported as inconclusive rather than passes. Its sessions correctly require the token on every request (MAP-SES01 passes).

These runs led to several fixes: results kept when a server issues no refresh token or crashes during login, a throttling check that copes with a broken refresh grant, and the per-flow identifier analysis above.

Why another scanner?

Good tools already exist, and this one is meant to sit next to them, not replace them:

mcp-authprobe focuses on what only an active, authorized test can confirm, and uses check IDs (MAP-…) that do not clash with mcp-posture's (MCPP-…). mcp-posture reserves its own active IDs for this and points here; the two reports can be merged into one.

Install

Requires Node.js 22.19 or later.

# run without installing

npx mcp-authprobe --help

or install globally

npm install -g mcp-authprobe

Releases are published from GitHub Actions with npm trusted publishing; check the provenance on the package page before installing a security tool.

From source:

git clone https://github.com/Enigmacker/mcp-authprobe.git

cd mcp-authprobe npm ci npm run build node dist/cli.js --help

Try it in a minute: the lab

mcp-authprobe lab starts a small MCP server with its own OAuth authorization server on 127.0.0.1, so you can see every check at work without touching a real server:

# Terminal 1: a deliberately vulnerable server (or --profile secure)

npx mcp-authprobe lab

Terminal 2

npx mcp-authprobe scan http://127.0.0.1:8787/mcp --allow-private npx mcp-authprobe login http://127.0.0.1:8787/mcp --allow-private --out lab-grant.json npx mcp-authprobe scan http://127.0.0.1:8787/mcp --allow-private --credentials-file lab-grant.json

Log in with the account test / test and click Allow.

The lab only listens on 127.0.0.1 or ::1 (--host, --port, default 8787; names such as localhost are refused so that no resolver can move it elsewhere), keeps everything in memory, and stops with Ctrl-C. Its access tokens are unsigned JWTs, so MAP-AUD01 can read their audience. It is vulnerable on purpose: never expose it.

Quick start

# 1. Create a secret and the proof to publish for your MCP host

mcp-authprobe ownership init mcp.example.com

2. Publish the proof (well-known file or DNS TXT), then keep the secret in your environment

export MCP_AUTHPROBE_SECRET='…'

3. Check the proof is visible

mcp-authprobe ownership verify mcp.example.com

4. Scan

mcp-authprobe scan https://mcp.example.com/mcp --sarif results.sarif --markdown summary.md

5. Log in once with a dedicated test account to create a test grant

mcp-authprobe login https://mcp.example.com/mcp --out ./test-grant.json

6. Full scan, including the refresh token checks

mcp-authprobe scan https://mcp.example.com/mcp --credentials-file ./test-grant.json

Without a valid proof the scan still runs discovery (the same read-only requests any MCP client sends before logging in), and every active check is reported as skipped.

For a local lab on your own machine:

mcp-authprobe scan http://127.0.0.1:8080/mcp --allow-private

Loopback targets with --allow-private do not need a proof.

Ownership proof

Active checks register clients, rotate tokens and send failing requests. To make sure they only ever hit servers whose operator agreed to it, the scanner requires a proof for every host it would contact: the MCP server host and, when it differs, the authorization server host.

The proof is a hash, bound to the host, of a secret that only you hold:

mcp-authprobe-verification=sha256:<hex(sha256("<host>:<secret>"))>

Publish it in one of two places:

Design choices:

• The secret never leaves your machine. Only its hash is published, so a proof found in the wild cannot be reused by someone else to scan your server.
• Proofs are host-bound. A proof for mcp.example.com is useless for any other host.
• The secret is read from `MCP_AUTHPROBE_SECRET` or `--secret-file`, never from the command line, so it does not land in shell history or process listings.
• Hosted authorization servers. If your authorization server is a third-party service on its own domain, you can only publish a proof if you control that domain (for example a custom domain). Check the provider's penetration testing policy before running active checks against it.

You can remove the proof as soon as you are done testing.

Refresh token checks

MCP clients are usually public clients, so OAuth 2.1 requires their refresh tokens to be rotated, and RFC 9700 recommends revoking the whole token family when an old one is reused. These properties cannot be read from metadata; they have to be exercised.

The checks need a test grant: a client and a refresh token obtained by logging in to your own server with a dedicated test account.

The easy way is mcp-authprobe login (see Interactive login), which writes the file for you. You can also write it by hand, readable only by you (chmod 600):

{

"client_id": "your-test-client-id", "refresh_token": "the-refresh-token", "client_secret": "only-for-confidential-clients", "token_endpoint_auth_method": "none" }

token_endpoint_auth_method is none (default for public clients), client_secret_post (default when a secret is present) or client_secret_basic.

The scan sends at most three refresh_token requests to the token endpoint found by discovery:

Important:

• The grant is consumed. On a compliant server, step 3 revokes it. Never use a grant you still need.
• If tokens are not rotated, MAP-RTK01 fails and the two replay checks are reported as not applicable.
• A throttled or unexpected response is reported as error (inconclusive), never as a pass.
• Token values never appear in output or reports; evidence only shows status codes and OAuth error codes.

Interactive login

mcp-authprobe login https://mcp.example.com