passmcp

[passmcp-server logo]

passmcp-server

passmcp, the Model Context Protocol server diagnostic, as MCP tools — so an agent can evaluate a server, or check an attestation about one, from inside the editor. Read-only, allowlisted, and it never sends a credential.

[Build] [Coverage] [Release] [Docs] [OpenSSF Scorecard] [License: GPL-3.0-only] [Go 1.26.9+]

[passmcp call invoking passmcp-server's passmcp_version and passmcp_check tools over stdio; passmcp_check scores passmcp's example toxic-pair server on loopback 97 out of 100]

Contents

Getting started

• Install — release archives, go install, make install, the container image, and an MCP host configuration
• Requirements — passmcp itself, and the Go floor to build from source
• Quick Start — ask the agent to evaluate a local server

The passmcp-server ecosystem

• The passmcp-server ecosystem — passmcp, passmcp-reporting, passmcp-server, passmcp-action, passmcp-graph, passmcp-registry, passmcp-lsp, passmcp-census, satellion.com

Library reference

• Capabilities at a glance — the current surface by theme
• Ecosystem comparison — short matrix; full table at docs/COMPARISON.md
• Benchmarks — headline numbers; full table at docs/BENCHMARKS.md
• Features — the allowlist, no credentials, read-only
• Configuration — two flags and their environment variables
• Examples — tool calls and results

Operational

• When not to use passmcp-server — limitations
• Development — make targets, the install contract, CI
• Security — what an agent can and cannot make it do
• Documentation — all reference docs
• Stability guarantees — tool names, arguments and results
• License

Install

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.

As a Go program

go install satellion.com/passmcp-server/cmd/[email protected]go install satellion.com/passmcp/cmd/[email protected]

Release binaries for Linux, macOS and Windows on amd64 and arm64 are on the releases page, with signed checksums and SLSA provenance.

From source, with make install

git clone https://github.com/sebastienrousseau/passmcp-servercd passmcp-servermake 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.

As a container image

docker pull ghcr.io/sebastienrousseau/passmcp-server:0.0.8

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.

In an MCP host

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.8"]    }  }}

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.

Requirements

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.

Quick Start

go install satellion.com/passmcp-server/cmd/[email protected]go install satellion.com/passmcp/cmd/[email protected]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.

The passmcp-server ecosystem

Every component is released at 0.0.8 and moves in lockstep: one version across the family, released together (docs/ecosystem.md).

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.

Capabilities at a glance

Ecosystem comparison

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.

See docs/COMPARISON.md for the evidence and complete matrix.

Benchmarks

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.

See docs/BENCHMARKS.md for methodology and full results.

Features

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.

Configuration

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-serverpassmcp-server --completion zsh > "${fpath[1]}/_passmcp-server"passmcp-server --completion fish > ~/.config/fish/completions/passmcp-server.fish

Examples

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

When not to use passmcp-server

• For a server that is a program. passmcp_check takes a Streamable HTTP URL. An agent starting arbitrary programs is a different trust decision; run passmcp check --stdio -- <command> yourself.
• For a server that needs credentials. Every run is --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.
• As a CI gate. Use passmcp-action, which keeps the report and fails the job.
• To check who signed an attestation. passmcp_verify_attestation checks structure and integrity; the signature is the envelope's, and cosign or gh attestation verify checks it.
• For many evaluations at once. Requests are answered in turn; a host that wants two at once starts two servers.

Development

make            # format, vet, lint, headers, tests, stdio smoke testmake test-race  # race detector, randomised ordermake image      # the container image for this machine, without goreleasermake family     # this repository's row in passmcp's family manifestmake lockstep   # the version is passmcp's latest releasemake versions   # every version-bearing file, and go.mod, name that releasemake coverage-json  # build/coverage.json, the document behind the badgemake 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.

Security

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.

Documentation

The four entry points, identical across every repo in the family:

• User Manual — passmcp's rendered manual: the phases, the checks, the report
• API reference — this module's packages
• Developer docs — toolchain, task map, reproducing every CI gate locally
• Ecosystem map — the family, the published artefacts, the lockstep version rule

Stability guarantees

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:

• Removing or renaming a tool, an argument or a structured result field
• Making an optional argument required
• Widening the default allowlist, sending a credential, or passing passmcp a flag that allows a mutating tool
• Changing a flag's or an environment variable's meaning

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.

License

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.

Back to Top