scout-mcp

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.

Contents

Getting started

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

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 — the three tools and the protocol surface
• Ecosystem comparison — beside running scout yourself
• Benchmarks — what the server adds to a run
• Features — the allowlist, no credentials, read-only
• Configuration — two flags and their environment variables
• Examples — tool calls and results

Operational

• When not to use scout-mcp — limitations
• Development — make targets, CI
• Security — what an agent can and cannot make it do
• Documentation — all reference docs
• Stability guarantees — tool names, arguments and results
• 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

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, with signed checksums and SLSA provenance.

As a container image

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:

{
  "mcpServers": {
    "scout": {
      "command": "scout-mcp",
      "args": ["--allow", ".internal.example.com"]
    }
  }
}

With the container image instead:

{
  "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 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 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.

The family manifest lives in scout at 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

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.

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 on the binaries built from this tree.

Features

An allowlist, on by default and narrow. With no configuration, scout_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). scout 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 scout runs.

No credentials. Every run is scout check <endpoint> --auth none, with SCOUT_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 scout.

Read-only, twice. Every tool here is annotated readOnlyHint: true. And no flag that allows a mutating tool is ever passed to scout, so scout invokes only the evaluated server's tools that declare readOnlyHint.

scout, not a copy of it. scout-mcp runs the scout program and reads the JSON report it prints; it does not link scout's engine. The version scout_version reports is whatever scout version says, and every safety property scout has holds, because the server can only ask for what scout'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: scout itself runs with an empty configuration file, whatever the operator's own scout configuration says.

Shell completions come from the flag set, so they list every flag:

scout-mcp --completion bash > /etc/bash_completion.d/scout-mcp
scout-mcp --completion zsh > "${fpath[1]}/_scout-mcp"
scout-mcp --completion fish > ~/.config/fish/completions/scout-mcp.fish

Examples

A tools/call for scout_check:

{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"scout_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 scout_verify_attestation, with endpoint optional; the second is scout_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 scout-mcp

• For a server that is a program. scout_check takes a Streamable HTTP URL. An agent starting arbitrary programs is a different trust decision; run scout 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 scout in a terminal with the credentials you were given for the rest.
• As a CI gate. Use scout-action, which keeps the report and fails the job.
• To check who signed an attestation. scout_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 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 scout's family manifest
make lockstep   # the version is scout's latest release

Every gate CI runs has a local form; DEVELOPMENT.md maps them. CI also builds scout 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 scout runs, and a refused endpoint never reaches scout. scout 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 scout'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 — scout'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

scout-mcp is pre-1.0, carries scout'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 scout 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 scout release underneath are not breaking. What a run reports is scout's, and scout'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.

scout-mcp is GPL-3.0-only like scout, the program it runs. It uses the Apache-2.0 scout-reporting verifier for attestations.

Back to Top