MCP

gonemaster-mcp exposes gonemaster-server’s admin API to Model Context Protocol (MCP) clients as a set of tools. It speaks stdio MCP and forwards requests to the server over HTTP; it does not run the engine itself.

Any MCP-compatible client or agent framework can drive it, for example Claude Code, Cursor, Cline, Zed, or a custom agent built on an MCP SDK. The client launches the bridge as a subprocess and talks to it over stdin/stdout.

Build

make build-gonemaster-mcp     # builds bin/gonemaster-mcp

Or install it onto your PATH:

make install-gonemaster-mcp

Configuration

The MCP client launches the bridge as a subprocess and passes configuration through environment variables. The only command-line flags are --help (-h) and --version (-v), which print and exit:

Variable	Default	Purpose
`GONEMASTER_URL`	`http://localhost:8080/api/v1`	Base URL of the gonemaster-server admin API. A bare host or origin is accepted; the `/api/v1` suffix is added automatically.
`GONEMASTER_TOKEN`	(unset)	Admin token sent as `Authorization: Bearer`. Leave unset for an open-mode server.
`GONEMASTER_MCP_ALLOW_WRITE`	(unset)	Set to `1` to register the mutating tools (`batch_enqueue`, `batch_cancel`, `cancel_job`). Unset by default, so a default install is read + `test_domain` only.

The bridge writes logs to stderr; stdout carries only the MCP protocol.

Authentication

The bridge mirrors gonemaster-client: when GONEMASTER_TOKEN is set it sends Authorization: Bearer <token> on every request; when it is unset it sends no credential, which works against a server running in open mode. If the server is in token mode and the token is missing or wrong, every call returns 401. Mint a token with gonemaster-server auth add-token; see ../server/authentication.md .

Connecting a client

The configuration is the same shape everywhere: a command to run and an env block. Point command at the built binary.

Claude Code

claude mcp add gonemaster \
  -e GONEMASTER_URL=http://localhost:8080 \
  -e GONEMASTER_TOKEN=gm_your_token_here \
  -- /path/to/gonemaster-mcp

Claude Desktop

Add an entry under mcpServers in claude_desktop_config.json:

{
  "mcpServers": {
    "gonemaster": {
      "command": "/path/to/gonemaster-mcp",
      "env": {
        "GONEMASTER_URL": "http://localhost:8080",
        "GONEMASTER_TOKEN": "gm_your_token_here"
      }
    }
  }
}

Omit GONEMASTER_TOKEN when the server runs in open mode.

Tools

Read tools (always available):

Tool	Purpose
`ping`	Check connectivity and report the server’s auth mode and whether the bridge is authenticated.
`test_domain`	Run a DNS test for a domain and wait for the result: grade, score, findings, and per-nameserver response times.
`run_get`	Fetch a stored run’s result by id (grade, score, findings, nameserver response times).
`latest_for`	List a domain’s most recent completed runs.
`run_search`	Search completed runs by domain, tag, status, severity, grade, or finish-time range.
`run_diff`	Compare two runs at the tag level (added / removed / severity-changed).
`spec_list_testcases`	List implemented testcases, optionally filtered to one module.
`spec_get_testcase`	Get a testcase’s module, description, and the tags it can emit with rendered messages.
`batch_list`	List recent batches (cohort runs), newest first, with status and completion; optional `label` tag-substring filter.
`batch_get`	Poll a batch: total, per-status counts, and completion.
`cohort_stats`	Grade and worst-severity distribution across a batch’s runs.
`cohort_tag_values`	Roll up the values a tag’s argument takes across a batch (by count, or by mean score with `weight_by_score`), with sample domains.
`failures_by_tag`	Rank the tags driving failures in a batch, with example domains.
`cohort_report`	Compare two snapshots of an analysis cohort, classifying every change as engine-driven or real, with movers and clusters.

cohort_tag_values is the generic primitive for “what values does argument <arg> of tag <tag> take across this batch?”. The (tag, arg) pair comes from the log-args inventory ; use spec_list_testcases and spec_get_testcase to discover a module’s tags. To rank the operators behind a batch by mean score, call it with tag=IPV4_ONE_ASN, arg=asn, weight_by_score=true; to also fold in ASNs that appear only in the *_DIFFERENT_ASN / *_SAME_ASN tags, call those tags too and union client-side.

cohort_report answers “did the cohort get worse, or did the engine start looking harder?”. Each tag row is classified new_in_engine, removed_from_engine, level_reclassified, cohort_change or unknown, and each moving domain rolls up to real, measurement, mixed or unknown. Called with no arguments it compares the two newest snapshots of the default public cohort. Snapshots are captured per batch, so it is also the batch-to-batch comparison for a cohort under analysis.

run_get, run_search, and latest_for include a batch_id field, so an agent can pivot from a known run to the batch (cohort) it belongs to. It is empty for ad-hoc single-domain runs.

The same tools include a public_id field. Build a shareable public report link as https://<host>/#/result/<public_id>. It is empty for runs that have no public id.

Write tools (registered only when GONEMASTER_MCP_ALLOW_WRITE=1):

Tool	Purpose
`batch_enqueue`	Enqueue a batch of domain tests (by `domains` or `from_tag`); returns a batch id to poll.
`batch_cancel`	Cancel a batch’s in-flight jobs and remove the batch.
`cancel_job`	Cancel a single queued or running job.

Verifying the connection

After configuring the client, call the ping tool. A healthy open-mode setup reports reachable: true and auth_mode: open. In token mode a correct token reports authenticated: true; a missing or wrong token reports authenticated: false with a hint to set GONEMASTER_TOKEN.

MCP