AI agent interface (MCP)

shepherd-mcp is a small Model Context Protocol server that lets an AI agent — the one in your editor, say — read a Shepherd organisation and propose pipeline changes for a human to review and apply. It never writes anything itself: every mutating action is a proposal, attributed to a named human, that lands in the normal review path. Reading and proposing are all it can do.

What the agent can do

The server exposes a read-plus-propose slice of the management API as MCP tools:

  • list_pipelines, get_pipeline — read the org’s pipelines.
  • list_collectors, get_collector, list_fleet_attributes — read the fleet, including each collector’s per-instance health.
  • validate_pipeline — check candidate text without saving it: does it parse and check out against the component schema, and which signals does it carry.
  • preview_matches — which collectors an existing pipeline’s stored matchers select (a proposal’s matchers are covered by propose_pipeline_revision).
  • simulate_relabel, simulate_logs — trace sample targets through relabel rules, or sample log lines through loki.process stages, step by step.
  • create_sandbox_run, get_sandbox_run — run a visual-builder graph in the sandbox against a real Alloy and read back what it captured.
  • propose_pipeline_revision — produce a fully-formed, validated revision proposal. It writes nothing; a human applies it through the usual path.

Give it a service account

The agent authenticates as a service account scoped to a single organisation, with propose capability — never apply. An org admin mints one from Access → Service accounts (or the API), then note its id and one-time secret. A propose-capability, editor-tier account is exactly right: it can read and propose, and the server has no path to apply even if the credential were broader.

Every call the agent makes is attributed to the human named in SHEPHERD_MCP_ON_BEHALF_OF, and that claim is verified against the human the service account was issued by — a machine cannot name someone it was not delegated to. Requests are also rate limited per credential, so a runaway agent cannot flood the API.

Download and run

Grab shepherd-mcp for your platform from the release archives (shepherd-mcp_<version>_<os>_<arch>; a .zip on Windows), or build it from source with go build ./cmd/shepherd-mcp. It speaks stdio and takes four environment variables, all required:

shell
export SHEPHERD_MCP_BASE_URL="https://shepherd.example.com"
export SHEPHERD_MCP_SERVICE_ACCOUNT_ID="<service-account-id>"
export SHEPHERD_MCP_SERVICE_ACCOUNT_SECRET="<service-account-secret>"
export SHEPHERD_MCP_ON_BEHALF_OF="you@example.com"

./shepherd-mcp

A missing variable is a hard error, not a reduced-safety default: the agent has no identity to act under without all four.

Wire it into an editor

Most MCP-capable clients take a command and its environment. The shape below is typical (consult your client for the exact file); the secret is best supplied from your shell or a secret store rather than committed:

mcp config
{
  "mcpServers": {
    "shepherd": {
      "command": "/path/to/shepherd-mcp",
      "env": {
        "SHEPHERD_MCP_BASE_URL": "https://shepherd.example.com",
        "SHEPHERD_MCP_SERVICE_ACCOUNT_ID": "<service-account-id>",
        "SHEPHERD_MCP_SERVICE_ACCOUNT_SECRET": "<service-account-secret>",
        "SHEPHERD_MCP_ON_BEHALF_OF": "you@example.com"
      }
    }
  }
}

The agent’s proposals never reach the auto-applying GitOps path, and it cannot apply a change itself. A human reviews and applies every revision it produces — the agent speeds up authoring, it does not gain write access to the fleet.