mcpreflight docs / check your endpoint

Check your MCP endpoint before clients depend on it

If you ship an MCP server, the failure you care about is the boring one: the endpoint stops answering initialize, or tools/list starts returning a schema a client cannot parse. This page is the shortest path to catching that in your own repository, on every pull request. Three copy-paste blocks: a GitHub Action, a one-line npx command, and a status badge.

Every check here is read-only. It sends an MCP initialize handshake and a tools/list request against a URL you name, then validates the response shape and tool schemas. It does not call your tools, does not send credentials, and does not attempt payment on x402 endpoints.

1. GitHub Action

Add this file as .github/workflows/mcp-check.yml. It runs on pull requests and fails the job when the report status is FAIL or UNKNOWN.

name: MCP Trust Check
on: [pull_request]

jobs:
  mcp-trust:
    runs-on: ubuntu-latest
    steps:
      - uses: xka0085-byte/mcpreflight@v1
        with:
          endpoint: https://your-mcp-server.example/mcp
          mode: schema
          format: markdown

Inputs: endpoint (required), mode (schema, inspect, baseline, drift; default schema), format (default markdown), baseline (path used by drift), and fail-on (default true; set false for an informational run). Exit codes are stable: 0 PASS, 1 FAIL, 2 UNKNOWN or network error, 3 usage error. Point it at a public test endpoint; do not put tokens or private keys in workflow inputs.

2. Run it locally with npx

Node.js 18 or newer. No API key, no wallet, no server code.

npx @eidonze/mcpreflight schema https://your-mcp-server.example/mcp

Add --json for machine-readable output, or --format=markdown to match the Action report. For an x402 paid endpoint, use npx @eidonze/mcpreflight inspect https://your-api.example/paid --method=POST: it reads the 402 challenge document without signing, paying, or settling anything.

3. Status badge

After your endpoint is listed in the Trust Directory, the badge renders the last scan status together with the scan date, so a stale badge is visibly stale rather than silently green. Replace SLUG with the registry name as it appears in the directory.

[![mcpreflight](https://xka0085-byte.github.io/mcpreflight/trust/badge/SLUG.svg)](https://xka0085-byte.github.io/mcpreflight/trust/p/SLUG.html)

If your server is not in the registry yet, use your own workflow badge instead, so the badge reflects a check that actually ran:

[![MCP Trust Check](https://github.com/OWNER/REPO/actions/workflows/mcp-check.yml/badge.svg)](https://github.com/OWNER/REPO/actions/workflows/mcp-check.yml)

What this check does not tell you

It is a protocol and schema preflight, not a security review. Read the list before you put it on a page:

• No tool calls. Runtime behaviour, data handling and permission scope are not observed, so a passing check says nothing about what a tool does when invoked.
• No authentication testing. Endpoints behind auth come back as AUTH_GATED or UNKNOWN, and are classified rather than counted as failures. The check does not bypass, test or evaluate your auth.
• No security or supply-chain audit. Malicious code, prompt injection and dependency risk are out of scope.
• No payment verification. For x402, the check reads the challenge shape; it does not sign, settle, or confirm delivery.
• Point in time. A result describes the response observed during that run against that URL. An endpoint can pass today and change tomorrow, and a self-hosted endpoint behind a cold start or a rate limit may report UNKNOWN rather than FAIL.
• Not a certification. It does not certify conformance to any spec beyond the response shapes it inspects, and it is not affiliated with any registry or vendor.

Related: test a remote MCP server, what the schema check validates, gating in CI, common handshake failures, x402 preflight.

Source: github.com/xka0085-byte/mcpreflight (MIT). Checks are read-only by design; report any false positive with the command and redacted output.