scout-mcp

<!-- 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/scout/main/.github/logo.svg" alt="scout-mcp logo" width="128" />
</p>

<h1 align="center">scout-mcp</h1>

<p align="center">
  scout, 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/scout-mcp/actions"><img src="https://img.shields.io/github/actions/workflow/status/sebastienrousseau/scout-mcp/ci.yml?style=for-the-badge&logo=github" alt="Build Status" /></a>
  <a href="https://github.com/sebastienrousseau/scout-mcp/pkgs/container/scout-mcp"><img src="https://img.shields.io/badge/ghcr.io-scout--mcp-fc8d62?style=for-the-badge&logo=docker&logoColor=white" alt="Container image" /></a>
  <a href="https://pkg.go.dev/github.com/sebastienrousseau/scout-mcp"><img src="https://img.shields.io/badge/go.dev-reference-007d9c?style=for-the-badge&logo=go&logoColor=white" alt="Go Reference" /></a>
  <a href="https://scorecard.dev/viewer/?uri=github.com/sebastienrousseau/scout-mcp"><img src="https://img.shields.io/ossf-scorecard/github.com/sebastienrousseau/scout-mcp?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?style=for-the-badge" alt="License: GPL-3.0-only" /></a>
  <a href="#requirements"><img src="https://img.shields.io/github/go-mod/go-version/sebastienrousseau/scout-mcp?style=for-the-badge&logo=go&logoColor=white&label=Go" alt="Minimum Go version" /></a>
</p>

---

## Contents

**Getting started**

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

**The scout-mcp ecosystem**

- [The scout-mcp ecosystem](#the-scout-mcp-ecosystem) — `scout`, `scout-reporting`, `scout-action`, `scout-mcp`, `scout-lsp`, `scout-census` at a glance

**Reference**

- [Capabilities at a glance](#capabilities-at-a-glance) — the three tools and the protocol surface
- [Ecosystem comparison](#ecosystem-comparison) — beside running scout yourself
- [Benchmarks](#benchmarks) — what the server adds to a run
- [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 scout-mcp](#when-not-to-use-scout-mcp) — limitations
- [Development](#development) — make targets, 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

`scout_check` runs the `scout` program. **scout must be installed and on
`PATH`, or named with `--scout`**, for that tool to work; the container
image carries it. `scout_verify_attestation` needs nothing but scout-mcp.

### As a Go program

```sh
go install github.com/sebastienrousseau/scout-mcp/cmd/scout-mcp@v0.0.8
go install github.com/sebastienrousseau/scout/cmd/scout@v0.0.8
```

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

### As a container image

```sh
docker pull ghcr.io/sebastienrousseau/scout-mcp:0.0.8
```

The image is scout's own release image with scout-mcp added: distroless,
non-root, linux/amd64 and linux/arm64, with scout at `/usr/local/bin/scout`
and scout-mcp started with `--scout` pointing at it.

### In an MCP host

scout-mcp 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": {
    "scout": {
      "command": "scout-mcp",
      "args": ["--allow", ".internal.example.com"]
    }
  }
}
```

With the container image instead:

```json
{
  "mcpServers": {
    "scout": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "ghcr.io/sebastienrousseau/scout-mcp: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 SCOUT_MCP_ALLOW=host.docker.internal`
to the arguments.

The server is listed in the official MCP Registry as
`io.github.sebastienrousseau/scout-mcp`; [`server.json`](server.json) is
that listing.

---

## Requirements

| Requirement | Floor | Enforced by |
|---|---|---|
| scout | on `PATH`, or `--scout`; the version this one is in lockstep with | CI builds scout 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 | `scout_check` refuses any other URL before scout 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 github.com/sebastienrousseau/scout-mcp/cmd/scout-mcp@v0.0.8
go install github.com/sebastienrousseau/scout/cmd/scout@v0.0.8
claude mcp add scout -- scout-mcp
```

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 scout and fix what fails.

The agent calls `scout_check`, which runs
`scout 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 scout-mcp ecosystem

One engine, three surfaces, five satellites. This repository is the
distribution surface: its deliverable is a registry listing, so scout is
where agents look for tools.

| Component | Purpose | Use case |
| :--- | :--- | :--- |
| [`scout`](https://github.com/sebastienrousseau/scout) | The engine, every check, and the CLI, TUI and web surfaces (GPL-3.0-only) | Evaluate a server and write the statement |
| [`scout-reporting`](https://github.com/sebastienrousseau/scout-reporting) | The attestation format, its schema and the offline verifier (Apache-2.0) | Gate on a statement in a gateway, registry or pipeline |
| [`scout-action`](https://github.com/sebastienrousseau/scout-action) | The GitHub Action and GitLab template wrapping the published image by digest (Apache-2.0) | Run scout in CI without installing it |
| **`scout-mcp`** | scout's diagnostics as read-only MCP tools (GPL-3.0-only) | Evaluate a server from inside an editor |
| `scout-lsp` | A language server over MCP artefacts (planned) | Hover a check id for its remediation |
| `scout-census` | The published reliability census (planned) | Reproduce the numbers |

The family manifest lives in scout at
[`docs/ecosystem.md`](https://github.com/sebastienrousseau/scout/blob/main/docs/ecosystem.md);
`make family` checks this repository's row against it. Every lockstep
repository carries scout's version; this one wraps scout's release, so its
version is scout's latest, exactly.

---

## Capabilities at a glance

| Area | Capability | Status |
| :--- | :--- | :--- |
| Evaluate | `scout_check`: score, grade, counts and up to 25 failing checks for an allowlisted Streamable HTTP endpoint, optionally narrowed to some of scout's nine phases | Stable |
| Verify | `scout_verify_attestation`: structure, subject digest and target of a scout attestation, offline | Stable |
| Identify | `scout_version`: scout-mcp's version and the scout it runs | Stable |
| Results | Text for the agent, plus `structuredContent` matching each tool's `outputSchema` | Stable |
| Protocol | stdio; handshake 2025-11-25, 2025-06-18, 2025-03-26; `server/discover` for 2026-07-28; `ping` | Stable |
| Servers that are programs (`--stdio`) | not through a tool; run `scout check --stdio` yourself | Out of scope |
| Credentials | never sent; every run is `--auth none` | Out of scope by design |

---

## Ecosystem comparison

The alternative is running scout in a terminal and pasting the report into
the conversation, or poking the server by hand in an inspector. scout-mcp
is the first with the decisions made for an agent: 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 |
| :--- | :---: | :---: | :---: |
| **scout-mcp** | yes | yes — loopback unless `--allow` | yes |
| `scout check` in a terminal | no | the operator types the URL | yes |
| [MCP Inspector](https://github.com/modelcontextprotocol/inspector) | no — a UI for a person | the operator types the URL | no |

---

## Benchmarks

The server adds a process start and a JSON round trip to a run; the run
itself is scout's, and bounded at five minutes. Measured with
[hyperfine](https://github.com/sharkdp/hyperfine) on the binaries built
from this tree.

| Scenario | Result | Environment |
| :--- | ---: | :--- |
| Start, `initialize`, `tools/list`, `scout_version`, exit | 16 ms mean | Apple A18 Pro, Go 1.27.1, 2026-