Evaluate an MCP server with passmcp and verify its attestations, from inside the agent. Read-only.
Getting started
go install, make install, the container image, and an MCP host configurationThe passmcp-server ecosystem
passmcp, passmcp-reporting, passmcp-server, passmcp-action, passmcp-graph, passmcp-registry, passmcp-lsp, passmcp-census, satellion.comLibrary reference
docs/COMPARISON.mddocs/BENCHMARKS.mdOperational
passmcp_check runs the passmcp program. passmcp must be installed and on
PATH, or named with --passmcp, for that tool to work; the container
image carries it. passmcp_verify_attestation needs nothing but passmcp-server.
go install satellion.com/passmcp-server/cmd/passmcp-server@v0.0.4
go install satellion.com/passmcp/cmd/passmcp@v0.0.4
Release binaries for Linux, macOS and Windows on amd64 and arm64 are on the releases page, with signed checksums and SLSA provenance.
make installgit clone https://github.com/sebastienrousseau/passmcp-server
cd passmcp-server
make install PREFIX="$HOME/.local"
make install builds the binary and its bash, zsh and fish completions and
installs them under PREFIX (default /usr/local), staged under DESTDIR
when a packager sets it. make uninstall removes them. The
GNUmakefile holds the contract, and CI checks the staged tree
on every push.
docker pull ghcr.io/sebastienrousseau/passmcp-server:0.0.4
The image is passmcp's own release image with passmcp-server added: distroless,
non-root, linux/amd64 and linux/arm64, with passmcp at /usr/local/bin/passmcp
and passmcp-server started with --passmcp pointing at it.
passmcp-server speaks MCP over stdio, so a host starts it as a child process.
For Claude Desktop (claude_desktop_config.json), Claude Code (.mcp.json)
and other hosts that read an mcpServers block:
{
"mcpServers": {
"passmcp": {
"command": "passmcp-server",
"args": ["--allow", ".internal.example.com"]
}
}
}
With the container image instead:
{
"mcpServers": {
"passmcp": {
"command": "docker",
"args": ["run", "-i", "--rm", "ghcr.io/sebastienrousseau/passmcp-server:0.0.4"]
}
}
}
Inside a container, loopback is the container itself. To evaluate a server
on the host, run the container with --network host on Linux, or point at
host.docker.internal and add -e PASSMCP_SERVER_ALLOW=host.docker.internal
to the arguments.
The server is listed in the official MCP Registry as
com.sebastienrousseau/passmcp-server; server.json is
that listing.
| Requirement | Floor | Enforced by |
|---|---|---|
| passmcp | on PATH, or --passmcp; the version this one is in lockstep with | CI builds passmcp at that tag and evaluates this server with it |
| Go (building from source) | the go directive in go.mod | CI tests on that version and on latest stable, on Linux, macOS and Windows |
| An MCP host | any that starts stdio servers and speaks revision 2025-03-26 or later | the handshake negotiates 2025-11-25, 2025-06-18 or 2025-03-26, and 2026-07-28 through server/discover |
| The server under test | a Streamable HTTP endpoint on the allowlist | passmcp_check refuses any other URL before passmcp runs |
The Go floor is raised only when a release needs a language feature, on a patch release like everything else pre-1.0, and the changelog says so.
go install satellion.com/passmcp-server/cmd/passmcp-server@v0.0.4
go install satellion.com/passmcp/cmd/passmcp@v0.0.4
claude mcp add passmcp -- passmcp-server
Then, with an MCP server of your own listening on
http://127.0.0.1:3000/mcp, ask the agent:
Evaluate my MCP server at http://127.0.0.1:3000/mcp with passmcp and fix what fails.
The agent calls passmcp_check, which runs
passmcp check http://127.0.0.1:3000/mcp --auth none --output json and
returns the score, the grade and every failing check with its detail and a
link to the fix. Loopback needs no configuration; any other host must be
named with --allow first.
Every component is released at 0.0.4 and moves in lockstep: one version across the family, released together (docs/ecosystem.md).
| Component | Purpose | Use case |
|---|---|---|
| passmcp | The MCP server diagnostic: checks in nine phases, every finding tied to the request that showed it, signed attestations | Test a server before your agents trust it, and gate it in CI |
| passmcp-reporting | The attestation format, its JSON Schemas and offline verifier, the graph model, and the agentgateway processor | Verify an attestation in a gateway, registry or pipeline |
| passmcp-server | passmcp's diagnostics as read-only MCP tools | Evaluate a server, or check an attestation, from inside the agent |
| passmcp-action | passmcp in GitHub Actions and GitLab CI, the image pinned by digest | Fail a build on the findings you choose |
| passmcp-graph | A local graph of agents, servers, tools and identities built from attestations | Find inherited risk and over-privilege, and gate on policy |
| passmcp-registry | A signed public scorecard of the MCP Registry's remote servers | Check a public server's standing before connecting to it |
| passmcp-lsp | A language server for MCP artefacts, with check-id hover from the guidance catalogue | Catch mistakes in server.json, tool schemas and client configuration while editing |
| passmcp-census | The published reliability census: dataset, methodology, disclosure log and reproduction command | Cite ecosystem-wide reliability figures, and reproduce them |
| satellion.com | The website, the Go module paths and the format URIs | Read the manual, and resolve satellion.com/... imports |
This repository is the distribution surface: its deliverable is a registry
listing, so passmcp is where agents look for tools. It wraps passmcp's
release, so its version is passmcp's latest, exactly; make lockstep
checks that, make family checks this repository's row in the family
manifest, and make versions checks that every file naming the version,
and the passmcp-reporting module in go.mod, agree on it.
| Area | Capability | Status |
|---|---|---|
| Evaluate | passmcp_check: score, grade, counts and up to 25 failing checks for an allowlisted Streamable HTTP endpoint, optionally narrowed to some of passmcp's nine phases | Released in 0.0.1 |
| Verify | passmcp_verify_attestation: structure, subject digest and target of a passmcp attestation, offline | Released in 0.0.1 |
| Identify | passmcp_version: passmcp-server's version and the passmcp it runs | Released in 0.0.1 |
| Results | Text for the agent, plus structuredContent matching each tool's outputSchema | Released in 0.0.1 |
| Protocol | stdio; handshake 2025-11-25, 2025-06-18, 2025-03-26; server/discover for 2026-07-28; ping | Released in 0.0.1 |
Servers that are programs (--stdio) | not through a tool; run passmcp check --stdio yourself | Out of scope |
| Credentials | never sent; every run is --auth none | Out of scope by design |
The alternative is running passmcp in a terminal and pasting the report into the conversation, or poking the server by hand in an inspector. passmcp-server makes the decisions an agent should not: which hosts it may reach, that no credential travels, and a result sized for a context window.
| Approach | An agent can call it | Targets limited by the operator | Scored, with remediation links |
|---|---|---|---|
| passmcp-server | yes | yes — loopback unless --allow | yes |
passmcp check in a terminal | no | the operator types the URL | yes |
| MCP Inspector | no — a UI for a person | the operator types the URL | no |
See docs/COMPARISON.md for the evidence and complete matrix.
The server adds a process start and a JSON round trip to a run; the run itself is passmcp's, and bounded at five minutes. Measured with hyperfine on binaries built from this tree and passmcp 0.0.1, on a machine that was running other builds at the time, so the spread is wide and the minimum is the better guide.
| Scenario | Result | Environment |
|---|---|---|
Start, initialize, tools/list, passmcp_version, exit | 27.2 ms ± 22.2 ms mean, 6.2 ms min (50 runs) | Apple A18 Pro, Go 1.27.1, 2026-09-29, load average 19 |
| passmcp's full stdio evaluation of passmcp-server | 242.3 ms ± 80.5 ms mean, 148.5 ms min (30 runs) | same |
passmcp_check against a server | passmcp's own timings, in its report | the target server |
See docs/BENCHMARKS.md for methodology and full results.
An allowlist, on by default and narrow. With no configuration,
passmcp_check evaluates loopback addresses only: localhost, any
*.localhost name, and loopback IPs. --allow names more hosts, exactly
or as .example.com for every subdomain (not the apex). passmcp makes real
requests to the endpoint it is given, and an agent choosing that endpoint
from a prompt is exactly the situation in which a request should not go
anywhere the operator did not name. A URL that is not http or https, or
that carries credentials in it, is refused before passmcp runs.
No credentials. Every run is passmcp check <endpoint> --auth none, with
PASSMCP_CONFIG pointing at an empty configuration file, so no profile or
defaults block the operator wrote for their own use can add a credential,
switch on mutations or redirect the report. The operator's secrets do not
travel to wherever an agent points passmcp.
Read-only, twice. Every tool here is annotated readOnlyHint: true.
And no flag that allows a mutating tool is ever passed to passmcp, so passmcp
invokes only the evaluated server's tools that declare readOnlyHint.
passmcp, not a copy of it. passmcp-server runs the passmcp program and reads
the JSON report it prints; it does not link passmcp's engine. The version
passmcp_version reports is whatever passmcp version says, and every safety
property passmcp has holds, because the server can only ask for what passmcp's
own flags allow.
Answers an agent can act on. A failing check comes with its id, severity, detail and a documentation link. A statement that does not verify is a result saying why, not a tool error. A server that fails everything returns the first 25 failures and says it truncated.
| Flag | Environment | Default | Meaning |
|---|---|---|---|
--allow | PASSMCP_SERVER_ALLOW | empty: loopback only | Hosts passmcp_check may evaluate besides loopback, comma-separated; a leading dot allows subdomains |
--passmcp | PASSMCP_SERVER_PASSMCP | passmcp on PATH | Path of the passmcp program |
--version | — | — | Print the version and exit |
--completion | — | — | Print a completion script for bash, zsh or fish, and exit |
A flag overrides its environment variable. Nothing else is read: passmcp itself runs with an empty configuration file, whatever the operator's own passmcp configuration says.
Shell completions come from the flag set, so they list every flag:
passmcp-server --completion bash > /etc/bash_completion.d/passmcp-server
passmcp-server --completion zsh > "${fpath[1]}/_passmcp-server"
passmcp-server --completion fish > ~/.config/fish/completions/passmcp-server.fish
A tools/call for passmcp_check:
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"passmcp_check","arguments":{"endpoint":"http://127.0.0.1:3000/mcp","phases":["handshake","catalog"]}}}
arguments for the other two:
{"statement": "<the attestation's JSON text>", "endpoint": "https://mcp.example.com/mcp"}
{}
The first is passmcp_verify_attestation, with endpoint optional; the
second is passmcp_version, which takes no arguments. An unknown argument
is refused rather than ignored, so a misspelling is reported.
To see the handshake and the tool list without a host:
make smoke
passmcp_check takes a Streamable
HTTP URL. An agent starting arbitrary programs is a different trust
decision; run passmcp check --stdio -- <command> yourself.--auth none, so
the evaluation is what an unauthenticated client sees. Run passmcp in a
terminal with the credentials you were given for the rest.passmcp_verify_attestation
checks structure and integrity; the signature is the envelope's, and
cosign or gh attestation verify checks it.make # format, vet, lint, headers, tests, stdio smoke test
make test-race # race detector, randomised order
make image # the container image for this machine, without goreleaser
make family # this repository's row in passmcp's family manifest
make lockstep # the version is passmcp's latest release
make versions # every version-bearing file, and go.mod, name that release
make coverage-json # build/coverage.json, the document behind the badge
make install-smoke # install and uninstall under a staged DESTDIR
Every gate CI runs has a local form; DEVELOPMENT.md maps
them. CI also builds passmcp at the lockstep version and has it evaluate this
server over stdio, failing below 90 or on any failing check but
supply.provenance.
The endpoint an agent passes is checked against the allowlist before passmcp
runs, and a refused endpoint never reaches passmcp. passmcp runs with
--auth none and an empty configuration file, and with no flag that
allows a mutating tool; each of those is a test in internal/runner and
internal/server. What reaches the agent is bounded: at most 25 failures
per result, and passmcp's error output cut to its last 400 characters. CI
runs govulncheck on every push, and releases are signed with cosign
keyless and carry SLSA build provenance.
Report vulnerabilities according to SECURITY.md.
The four entry points, identical across every repo in the family:
| Document | Covers |
|---|---|
docs/ARCHITECTURE.md | How a call flows, the packages, and the settings every run is fixed to |
docs/adr/ | Decision records for this repository |
docs/COMPARISON.md | passmcp-server beside the other ways to run passmcp |
docs/BENCHMARKS.md | What the server adds to a run, and how it was measured |
docs/publishing.md | Publishing the registry listing |
docs/releases/ | Release highlights, one file per release |
server.json | The MCP Registry listing |
SECURITY.md | Disclosure policy, supported versions, what is guaranteed |
CONTRIBUTING.md | Signed-commit and DCO policy, what a change needs |
CHANGELOG.md | Per-release notes, and the lockstep version rule |
SUPPORT.md | Where to ask, and what to expect |
passmcp-server is pre-1.0, carries passmcp's version, and follows SemVer with the patch digit moving for everything until 1.0.
The breaking axis is what an agent or a host relies on. These are breaking:
Added tools, optional arguments and result fields, and a new passmcp release underneath are not breaking. What a run reports is passmcp's, and passmcp's own stability rule governs it.
Deprecation window. A deprecated tool or argument keeps working for at least one release after the release that announces it.
Licensed under the GNU General Public License v3.0 only.
passmcp-server is GPL-3.0-only like passmcp, the program it runs. It uses the Apache-2.0 passmcp-reporting verifier for attestations.
Source-derived launch command. Check the maintainer’s required arguments and credentials before running:
docker run -i --rm ghcr.io/sebastienrousseau/passmcp-server:0.0.3Merge this template into ~/Library/Application Support/Claude/claude_desktop_config.json. Keep existing servers. Add any arguments, credentials, and permissions required by the maintainer; this template has not been install-tested.
{
"mcpServers": {
"com-sebastienrousseau-passmcp-server": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/sebastienrousseau/passmcp-server:0.0.3"
]
}
}
}Restart Claude Desktop completely for changes to take effect. Confirm the server appears connected in the client’s tool list, then try a read-only example from its documentation.
Claude Desktop setup referenceghcr.io/sebastienrousseau/passmcp-server:0.0.3dockerpassmcp works with any MCP-compatible client. Copy the config snippet from the Configuration section above and add it to the file shown for your client, then restart the application.
~/Library/Application Support/Claude/claude_desktop_config.jsonRestart Claude Desktop completely for changes to take effect.~/.cursor/mcp.jsonRestart Cursor for changes to take effect..vscode/mcp.jsonReload VS Code window for changes to take effect.~/.codeium/windsurf/mcp_config.jsonRestart Windsurf for changes to take effect..mcp.jsonSave at the project root, then start Claude Code in that project and review the MCP server approval prompt. Keep real credentials out of shared files.