Scan an MCP endpoint in CI with the AdminKit GitHub Action
To scan an MCP endpoint in CI before an agent trusts it, add AdminKit's GitHub Action to a workflow, give it the server's URL and keep fail-on at critical. On every push or schedule it sends only initialize and tools/list, without credentials, and fails the build if the server answers anonymous clients. Netbase shares the action on request.
By AdminKit team, Netbase JSC · Updated
Key takeaways
- The action runs AdminKit’s open-source, read-only MCP probe against one URL. It sends
initializeandtools/listwithout credentials and never sendstools/call. - It reports four kinds of finding: no authentication, a tool list readable anonymously, high-risk tool names, and no TLS. Each finding lowers a 0-100 exposure score.
fail-ondecides when the step goes red:none,warningorcritical(the default). An unreachable target always fails the step.- Run it on every push and on a schedule. Exposure can change without anyone touching the server’s code.
How do I scan an MCP endpoint in CI before an agent trusts it?
Make the scan a required step that runs before an MCP server goes into an agent’s configuration, and again on a schedule after that. It automates one part of vetting an MCP server before you connect it to an AI agent: the check for anonymous access and an exposed tool list. Scan only servers you own, or servers you are evaluating for your own use within their published terms.
- Get the action. It is not on the GitHub Marketplace. Ask our team and Netbase shares a checkout with you.
- Add the workflow. Copy the workflow YAML shown further down this page into
.github/workflows/. Pinuses:to a commit SHA, not@main. - Set the inputs. Put the server’s HTTPS endpoint in
url. Keepfail-on: critical(the default), so a server that answers without credentials turns the step red. - Run it on push and on a schedule. Exposure can change without a code change, so a weekly run catches what a push-only run misses.
- Block on the result. Make the scan job a required check on the branch that holds your agent’s configuration, so a red scan stops the change that would connect the agent.
- Read the job summary. Look at the status, the score and every tool name listed, not just the colour of the step.
What do a pass and a fail look like?
| Outcome | What the job summary shows | Step with fail-on: critical |
|---|---|---|
| Pass | Status: **ok**, Score: 100, “no anonymous access found” and “No findings.” | Green |
| Fail | Status: **fail**, a score below 100 and a table of findings, such as initialize accepted without authentication | Red |
| Warn | Status: **warn**, only medium findings, such as plain HTTP while auth is required | Green (red with fail-on: warning) |
| Skipped | The target resolved only to private or loopback addresses, so nothing was sent | Green, but nothing was checked |
| Error | The target could not be reached; score is empty | Always red |
A full example of a failing summary is further down this page.
What does the scan not prove?
A green step is narrower than “safe to connect”. The scan does not:
- Audit the server’s code or test what any tool really does when called. It never sends
tools/call. - Read tool descriptions. It flags risky tool names only. Text in a description aimed at the model is a separate check; see how to check for MCP tool poisoning.
- Test your OAuth setup. A pass means
initializewas refused without credentials. It does not check token audience, scopes or token passthrough. - See what a signed-in client sees. Once auth is in place, the probe never reaches
tools/list, so the tool list behind it goes unchecked. - Check provenance or version pinning of the server you are about to connect.
- Cover local stdio servers. It needs an HTTP URL; a server your client starts as a local process has none.
For the controls a scan cannot give you, such as checking each token, allowlisting tools and logging every call, read what a security gateway for MCP servers does and when you need one.
What does this action check?
The action installs adminkit-mcp (the same package behind AdminKit’s public MCP server) at the exact commit your workflow pins, then runs its endpoint probe against one URL you give it. The probe’s only JSON-RPC 2.0 calls (MCP messages use that request/response format) are initialize and tools/list — never tools/call — so it is safe to point at a server that real clients are actively using. It checks for:
- the server accepting
initializewith no credentials at all (“no auth required”) - the tool list being readable anonymously once
initializesucceeds - tool names that look like they grant shell, file or network access (“dangerous tool exposed”)
- the endpoint not being served over TLS
and produces a 0-100 exposure score (lower is worse), a GitHub Actions job summary, and score / findings-json step outputs. Where a server declares tool annotations like destructiveHint, a reader of the results should still treat a declared hint as a signal rather than a verified fact, since the specification doesn’t make annotations trustworthy by default; the probe itself judges risk from tool names only.
Which requests does the probe send?
Every request the probe makes is either a read or a protocol handshake. The full list, in order:
| Request | When | Why |
|---|---|---|
POST <url> with JSON-RPC initialize | Always | Tests whether the server answers a client that presents no credentials |
POST <url> with JSON-RPC tools/list | Only if initialize succeeded | Reads the tool names an anonymous client can see |
GET <origin>/sse | Only if the URL does not answer as streamable HTTP | Tries the older HTTP+SSE transport, then repeats the same two calls over it |
GET <origin>/.well-known/oauth-protected-resource | Always | Records the server’s published OAuth metadata, if any |
GET <authorization server>/.well-known/oauth-authorization-server | If the metadata names an authorization server | Records that server’s metadata |
The two metadata requests follow the discovery flow in the MCP authorization specification, which requires an HTTP MCP server that uses authorization to publish OAuth 2.0 Protected Resource Metadata. The probe stores what it finds as evidence; it does not try to obtain a token.
What do the findings and the score mean?
The score starts at 100 and loses points for each finding, according to its severity. The step status follows the worst severity: any high or critical finding makes the scan fail, a lower-severity finding alone makes it warn, and no findings make it ok.
| Finding id | Severity | Score penalty | Raised when |
|---|---|---|---|
mcp.no_auth_required | high | −25 | initialize succeeds with no credentials |
mcp.tools_exposed_anonymously | medium | −15 | tools/list then returns a tool list |
mcp.dangerous_tool_exposed | critical | −40 | A listed name contains a pattern such as shell, exec, command, delete, write_file or fetch_url |
mcp.no_tls | medium | −15 | The URL uses http:// instead of https:// |
A fully open server with a shell-like tool on plain HTTP therefore scores 100 − 25 − 15 − 40 − 15 = 5. The name match is a pattern, not an analysis of what the tool does: a harmless tool called system_status matches system, and a dangerous tool with a bland name does not match at all. Read the tool names in the job summary yourself before you decide what the score means for your server.
How do you add it to a workflow?
Netbase shares the action with teams on request — talk to our team and we will send you a checkout. The example below is the complete workflow shipped with the action itself:
name: Scan MCP endpoint
on:
push:
branches: [main]
schedule:
- cron: "0 6 * * 1" # weekly, Monday 06:00 UTC
jobs:
scan:
runs-on: ubuntu-latest
steps:
- name: Scan our public MCP endpoint
id: scan
uses: NetbaseJSC/adminkit/integrations/github-action@main
with:
url: https://mcp.example.com/mcp
fail-on: critical
- name: Show the score
run: echo "AdminKit MCP exposure score: ${{ steps.scan.outputs.score }}"
Replace url with your own MCP endpoint and uses: with a pinned tag or commit SHA rather than @main once you’ve picked a version to rely on — the action is not published to the GitHub Marketplace, so a pinned ref is the only way to version it. GitHub’s security hardening guide recommends pinning third-party actions to a commit SHA, because a tag can be moved or deleted, and setting the default GITHUB_TOKEN permission to read-only. The scan needs no write access, so a permissions: contents: read block on the job is enough.
The action itself is a composite action: it sets up Python 3.12, installs the probe package from the action’s own checkout, and runs a short wrapper script that formats the result. There is no container and no separate scanning service.
Which inputs does it take?
| Input | Required | Default | What it does |
|---|---|---|---|
url | yes | — | MCP endpoint URL to scan. |
fail-on | no | critical | none never fails the step on findings; warning fails on any finding; critical fails on a high/critical-severity finding. |
api-key | no | "" | Not used by the scan. The probe is anonymous-only and never sends it to the scanned target. |
allow-private | no | false | Allow scanning a private/loopback target — only for CI jobs scanning a fixture server they started themselves. |
A scan that cannot reach url at all always fails the step, regardless of fail-on. A target refused for being private/loopback (allow-private: false) is reported as skipped and does not fail the step. The probe decides this by resolving the hostname first: if every address it resolves to is private, loopback, link-local, reserved or multicast, nothing is sent.
Which outputs can later steps use?
| Output | Description |
|---|---|
score | 0-100 exposure score (lower is worse); empty if the target could not be reached. |
findings-json | JSON array: [{"id", "severity", "title", "detail", "fix_hint"}, ...]. |
- name: Scan
id: scan
uses: NetbaseJSC/adminkit/integrations/github-action@main
with:
url: https://mcp.example.com/mcp
fail-on: none
- run: echo "score was ${{ steps.scan.outputs.score }}"
How does fail-on map to a red or green step?
The probe produces one of five statuses, and fail-on decides which of them stop the job:
| Probe status | fail-on: none | fail-on: warning | fail-on: critical |
|---|---|---|---|
ok (no findings) | pass | pass | pass |
warn (only medium or lower findings) | pass | fail | pass |
fail (a high or critical finding) | pass | fail | fail |
skipped (private target refused) | pass | pass | pass |
error (target unreachable) | fail | fail | fail |
critical suits a production endpoint that must never accept anonymous clients: an open initialize is a high finding and turns the step red. warning is stricter and also catches a server on plain HTTP. none is for reporting only, for example a nightly job that records the score as a trend without blocking anyone.
What does the job summary look like?
The example below is illustrative: the server, its URL and its tools are invented, using the documentation domain example.com. The layout and the finding text are what the action’s wrapper writes to the job summary for a server that accepts anonymous clients and lists two tools over HTTPS.
## AdminKit MCP scan
- URL: `https://mcp.example.com/mcp`
- Status: **fail**
- Score: 20
- AdminKit API key configured: False (reserved for future dashboard submission; not used by this scan)
- 3 finding(s)
| Finding | Severity | Evidence | Fix |
| --- | --- | --- | --- |
| MCP server accepted `initialize` without authentication | high | `initialize` returned HTTP 200 with no credentials presented. | Require OAuth 2.1 (or another credential) before serving MCP requests; see the MCP authorization specification. |
| MCP tool list readable without authentication | medium | 2 tool(s) listed: get_status, run_shell | Gate `tools/list` behind authentication; anonymous clients should not enumerate tools. |
| A high-risk tool name is exposed anonymously | critical | Tool name(s) suggest shell/file/network access: run_shell | Treat these as highly privileged: require auth, an allow-list, and human approval before any call. |
With the default fail-on: critical, this run fails the step. After authentication is added, the same scan should show Status: **ok**, Score: 100 and “No findings.”, because initialize is then rejected and the probe never reaches tools/list.
How do you test against a server started in CI?
If your MCP server lives in the same repository, you can scan a fresh build before it is deployed. Start the server in the background in one step, wait for its port, and point the action at http://127.0.0.1:<port>/mcp with allow-private: true. The action’s own test suite works the same way, against a local fake MCP server. Expect an mcp.no_tls finding on a plain-HTTP local server; use fail-on: critical so that finding alone does not fail the build, and keep a separate scheduled job, with allow-private off, for the deployed HTTPS endpoint.
Why run this instead of a one-off manual check?
AdminKit’s MCP endpoint check tool page runs this same check live from a browser — see how to read an MCP endpoint check result for what its findings mean, and AdminKit’s MCP endpoint check vs mcpscan.ai for how the two compare if you’re choosing between them. The GitHub Action and the public MCP server’s check_mcp_endpoint tool both run the identical probe directly against the target, with no dependency on the website — which is exactly why running it in CI on every push, plus a weekly schedule, catches the case our guide to securing an MCP server calls out explicitly: exposure can change without anyone touching the server’s code, so a one-time check, from a browser or otherwise, only tells you about right now. If you’d rather run this same probe on demand from a chat prompt instead of CI, see check if your MCP server is exposed with an AI agent.
Where does AdminKit fit beyond detection?
The action’s own scanning logic is intentionally minimal and permanent: two anonymous JSON-RPC calls and a metadata read, nothing more. For enforcement rather than detection — blocking an unauthenticated call before it reaches your server, not just reporting that one got through — AdminKit’s MCP & Agent Gateway sits in front of the server itself, and Netbase deploys and runs it for you as a custom engagement — talk to our team about it. For detection, running this action in CI is the practical way to catch exposure regressions. See our AI agent builders page for the free checks and services for teams building on MCP. This action is part of AdminKit’s AI agents & MCP cluster of guides and tools for securing MCP servers.
This guide is general information, not a security audit of your specific network — see our disclaimer for what AdminKit's guidance does and does not commit to.
Frequently asked questions
Do I need an AdminKit account to use this action?
No. The scan itself is anonymous and needs no API key. The action does accept an optional api-key input, but the scan does not use it and never sends it to the scanned target.
How do I get the action into my workflow?
Ask our team at /contact/ and Netbase shares a checkout of the action with you. Reference it from your workflow with uses:, pinned to a tag or commit SHA rather than @main.
Can this action call tools on my MCP server, not just check it?
No. Its only JSON-RPC calls are initialize and tools/list — the same two calls the public MCP server's own probe sends — plus read-only GET requests for the server's published OAuth metadata. It never sends tools/call, so it is safe to run against a server that is actually in use.
What does fail-on actually control?
none never fails the step on findings; warning fails on any finding; critical (the default) fails only on a high or critical severity finding. A target that cannot be reached at all (DNS failure, connection refused, timeout) always fails the step, independent of fail-on, because that is a different signal than 'findings below threshold'.
Does this action check anything besides MCP exposure?
No — its scope is MCP endpoint exposure only. For DNS, mail authentication or TLS checks in CI, call AdminKit's Check API at api.adminkit.net directly from a workflow step; the OpenAPI reference lists the endpoints.
Can I test the action against a server my workflow starts itself?
Yes. Start the server on localhost in an earlier step and set allow-private: true. Without that input, a target whose hostname resolves only to private or loopback addresses is reported as skipped and the step does not fail. Leave allow-private off for any real endpoint.
Does a passing scan mean an AI agent can trust the server?
No. A pass means the server refused an anonymous initialize over HTTPS. It does not audit the server's code, read tool descriptions, or test token audience and scopes. Use it as one gate in a wider vetting checklist, not as a verdict.
Want AdminKit to watch this for you?
Free checks tell you the state today. Protective DNS and monitoring tell you when it changes.
Talk to an expert
Huy Nguyen (David), Founder & CEO, Netbase JSC
Ask whether this fix applies to your setup, or get a second pair of eyes on your DNS and mail records.