mcpreflight docs / remote preflight
Test a remote MCP server before connecting
Testing a remote MCP server means one thing: can this deployed endpoint complete an MCP initialize handshake and answer tools/list with valid schemas, right now, without you spawning any process? In our October 2026 scan of the official registry, only 48.8% of 9,991 remote endpoints passed that bar anonymously, and 115 endpoints that passed one week flipped to UNKNOWN the next. The command below gives you the same read-only verdict locally or in CI. Numbers: State of MCP Servers.
Most MCP testing advice covers local servers you run yourself. A deployed remote endpoint is a different problem: you have no process to spawn, no UI process model, and what you need is an unattended verdict your CI can gate on.
One command, read-only
npx @eidonze/mcpreflight schema https://your-mcp-server.example/mcp MCP Tool Schema Report - Status: PASS - Protocol: 2025-06-18 - Tools: 12
The check sends MCP initialize and tools/list only. No tools are called, no data is read, no keys are needed. Exit codes are stable for automation: 0 pass, 1 fail, 2 network error, 3 usage error.
Inspector or mcpreflight?
| MCP Inspector | mcpreflight | |
|---|---|---|
| Best at | Interactive debugging while you develop a local server | Unattended checks of remote deployed endpoints |
| Runs against | A process you spawn, or a UI session | Any reachable URL, no code access needed |
| CI gating | Possible with CLI smoke tests | Native: stable exit codes plus the mcp-trust-check GitHub Action |
| Scale | One server at a time | Powers a public directory of all 9,991 registry endpoints, rescanned weekly |
| x402 payments | Not covered | 402 challenge validation without paying |
They are complements, not rivals. Inspector while building, mcpreflight after deploying and in CI.
Gate every pull request
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
Full setup in MCP security CI. Common failures are catalogued in troubleshooting.