passmcp-server

<!-- SPDX-FileCopyrightText: 2026 Sebastien Rousseau <sebastian.rousseau@gmail.com> -->
<!-- SPDX-License-Identifier: GPL-3.0-only -->

<p align="center">
  <img src="https://raw.githubusercontent.com/sebastienrousseau/passmcp/main/.github/logo.svg" alt="passmcp-server logo" width="128" />
</p>

<h1 align="center">passmcp-server</h1>

<p align="center">
  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.
</p>

<p align="center">
  <a href="https://github.com/sebastienrousseau/passmcp-server/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/sebastienrousseau/passmcp-server/ci.yml?branch=main&style=for-the-badge&logo=github&label=Build" alt="Build" /></a>
  <a href="https://github.com/sebastienrousseau/passmcp-server/blob/main/DEVELOPMENT.md#coverage"><img src="https://img.shields.io/endpoint?url=https%3A%2F%2Fsebastienrousseau.com%2Fpassmcp-server%2Fcoverage.json&style=for-the-badge&logo=codecov&logoColor=white" alt="Coverage" /></a>
  <a href="https://github.com/sebastienrousseau/passmcp-server/releases"><img src="https://img.shields.io/github/v/release/sebastienrousseau/passmcp-server?style=for-the-badge&color=fc8d62&logo=github&label=Release" alt="Release" /></a>
  <a href="https://pkg.go.dev/satellion.com/passmcp-server"><img src="https://img.shields.io/badge/go.dev-reference-007d9c?style=for-the-badge&labelColor=555555&logo=go&logoColor=white" alt="Docs" /></a>
  <a href="https://scorecard.dev/viewer/?uri=github.com/sebastienrousseau/passmcp-server"><img src="https://img.shields.io/ossf-scorecard/github.com/sebastienrousseau/passmcp-server?style=for-the-badge&label=OpenSSF%20Scorecard&logo=openssf" alt="OpenSSF Scorecard" /></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-GPL--3.0--only-blue.svg?style=for-the-badge" alt="License: GPL-3.0-only" /></a>
  <a href="https://github.com/sebastienrousseau/passmcp-server/blob/main/DEVELOPMENT.md#requirements"><img src="https://img.shields.io/badge/go-1.26.9%2B-93450a.svg?style=for-the-badge&logo=go" alt="Go 1.26.9+" /></a>
</p>

<p align="center">
  <img src=".github/demo.gif" alt="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" width="100%" />
</p>

---

## Contents

**Getting started**

- [Install](#install) — release archives, `go install`, `make install`, the container image, and an MCP host configuration
- [Requirements](#requirements) — passmcp itself, and the Go floor to build from source
- [Quick Start](#quick-start) — ask the agent to evaluate a local server

**The passmcp-server ecosystem**

- [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](#capabilities-at-a-glance) — the current surface by theme
- [Ecosystem comparison](#ecosystem-comparison) — short matrix; full table at [`docs/COMPARISON.md`](docs/COMPARISON.md)
- [Benchmarks](#benchmarks) — headline numbers; full table at [`docs/BENCHMARKS.md`](docs/BENCHMARKS.md)
- [Features](#features) — the allowlist, no credentials, read-only
- [Configuration](#configuration) — two flags and their environment variables
- [Examples](#examples) — tool calls and results

**Operational**

- [When not to use passmcp-server](#when-not-to-use-passmcp-server) — limitations
- [Development](#development) — make targets, the install contract, CI
- [Security](#security) — what an agent can and cannot make it do
- [Documentation](#documentation) — all reference docs
- [Stability guarantees](#stability-guarantees) — tool names, arguments and results
- [License](#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

```sh
go install satellion.com/passmcp-server/cmd/passmcp-server@v0.0.8
go install satellion.com/passmcp/cmd/passmcp@v0.0.8
```

Release binaries for Linux, macOS and Windows on amd64 and arm64 are on
the [releases page](https://github.com/sebastienrousseau/passmcp-server/releases),
with signed checksums and SLSA provenance.

### From source, with `make install`

```sh
git 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](GNUmakefile) holds the contract, and CI checks the staged tree
on every push.

### As a container image

```sh
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:

```json
{
  "mcpServers": {
    "passmcp": {
      "command": "passmcp-server",
      "args": ["--allow", ".internal.example.com"]
    }
  }
}
```

With the container image instead:

```json
{
  "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`](server.json) is
that listing.

---

## Requirements

| 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`](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.

---

## Quick Start

```sh
go install satellion.com/passmcp-server/cmd/passmcp-server@v0.0.8
go install satellion.com/passmcp/cmd/passmcp@v0.0.8
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](https://github.com/sebastienrousseau/passmcp/blob/main/docs/ecosystem.md)).

| Component | Purpose | Use case |
| :--- | :--- | :--- |
| [passmcp](https://github.com/sebastienrousseau/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](https://github.com/sebastienrousseau/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](https://github.com/sebastienrousseau/passmcp-server) | passmcp's diagnostics as read-only MCP tools | Evaluate a server, or check an attestation, from inside the agent |
| [passmcp-action](https://github.com/sebastienrousseau/passmcp-action) | passmcp in GitHub Actions and GitLab CI, the image pinned by digest | Fail a build on the findings you choose |
| [passmcp-graph](https://github.com/sebastienrousseau/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](https://github.com/sebastienrousseau/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](https://github.com/sebastienrousseau/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](https://github.com/sebastienrousseau/passmcp-census) | The published reliability census: dataset, methodology, disclosure log and reproduction command | Cite ecosystem-wide reliability figures, and reproduce them |
| [satellion.com](https://github.com/sebastienrousseau/sat