GoCD MCP Server

GoCD MCP Server is a production-grade Model Context Protocol server that exposes GoCD pipelines over Streamable HTTP with per-user authentication via GoCD Personal Access Tokens, enabling MCP-capable agents to inspect and operate pipelines while enforcing GoCD's own RBAC. The server offers 17 tools across three risk tiers, including read-only, safe actions, and config editing, gated by a single TOOLSET switch, and includes an audit log, health probes, and typed compact outputs.

A production-grade Model Context Protocol https://modelcontextprotocol.io MCP server that exposes GoCD https://www.gocd.org/ over Streamable HTTP , authenticated per-user with GoCD Personal Access Tokens PAT . It lets MCP-capable agents Claude Code, Claude Desktop, IDE extensions, … inspect and operate GoCD pipelines — list and trigger pipelines, read statuses/history/console logs, pause/cancel, and optionally edit pipeline configuration — while GoCD's own RBAC is enforced for every call, because the server acts strictly as the authenticated user. Protocol: MCP revision 2025-11-25 , Streamable HTTP transport SDK: official modelcontextprotocol/go-sdk Language: Go 1.25+ Target: a single GoCD instance verified against GoCD 25.4.0 Features features Tools & resources tools--resources Requirements requirements Installation installation Configuration configuration Authentication & authorization authentication--authorization Running the server running-the-server Connecting an MCP client connecting-an-mcp-client Toolsets risk tiers toolsets-risk-tiers Architecture architecture Security security Logging & observability logging--observability Development development Troubleshooting troubleshooting Contributing contributing License license - 🔐 Per-user identity — the MCP client presents a GoCD PAT as a bearer token; the server validates it and acts as that user, so GoCD RBAC applies automatically. No shared service account. - 🧰 17 tools across three risk tiers — read-only, safe actions, and config editing — gated by a single TOOLSET switch. - 🧱 Typed, compact outputs — focused projections of GoCD's responses to keep token usage low. - 📓 Audit log — every mutating operation is logged login, action, target ; tokens are never logged. - 🩺 Health probes — /healthz liveness and /readyz checks GoCD reachability . - 🧪 Well-tested — unit domain , contract GoCD client via httptest , and end-to-end MCP over the real SDK client tests. Mutating tools carry MCP annotations destructiveHint / idempotentHint so the host can ask for user confirmation before running them. | Tool | Toolset | Kind | Description | |---|---|---|---| whoami | all | read | Authenticated GoCD login verifies the token | list pipelines | all | read | Dashboard pipelines with latest run status, pause/lock state optional group filter | get pipeline status | all | read | Pause / lock / schedulable state of a pipeline | get pipeline history | all | read | Past runs paginated via offset with stage statuses | get pipeline instance | all | read | One run's detail incl. per-stage and per-job state/result | get job console log | all | read | Console log of a job run last tail lines , default 200 | list agents | all | read | Build agents and their config/runtime state | get pipeline config | all | read | Full pipeline config + ETag needed to update | trigger pipeline | actions, full | action | Schedule a pipeline run | pause pipeline | actions, full | action | Pause a pipeline reason required | unpause pipeline | actions, full | action | Resume a paused pipeline | cancel stage | actions, full | action | Cancel a running stage | comment on pipeline | actions, full | action | Comment on a pipeline instance | update pipeline config | full | destructive | Replace a pipeline config optimistic locking via ETag/If-Match | create pipeline | full | destructive | Create a new pipeline in a group | update agent | full | destructive | Patch an agent enable/disable, resources, environments | delete pipeline | full | destructive | Delete a pipeline irreversible | Read-only mirrors of dashboard data, addressable by URI for a user/app to attach as context: gocd://dashboard — all pipelines and latest status gocd://agents — all build agents gocd://pipeline/{name}/config — a pipeline's configuration gocd://pipeline/{name}/history — a pipeline's recent runs - Go 1.25+ to build , or Docker - Network access to a GoCD server, and its URL GOCD BASE URL — required , no default - A GoCD Personal Access Token per user see below - TLS certificate/key for production or a TLS-terminating proxy php go install github.com/ivinco/gocd-mcp/cmd/gocd-mcp@latest - $GOBIN/gocd-mcp git clone https://github.com/ivinco/gocd-mcp.git cd gocd-mcp go build -o gocd-mcp ./cmd/gocd-mcp The image is multi-stage and runs on distroless/static as a non-root user nonroot , uid 65532 . It carries no configuration of its own: mount the config file and TLS certificates , and pass any overrides via environment variables . docker build -t gocd-mcp . Recommended: config file + certs mounted, secrets/overrides via env. Prepare a config.yaml see config.example.yaml /Ivinco/gocd-mcp/blob/master/config.example.yaml and your TLS material, then mount them read-only and point CONFIG FILE at the mounted path: docker run --rm -p 8443:8443 \ -v /etc/gocd-mcp/config.yaml:/etc/gocd-mcp/config.yaml:ro \ -v /etc/gocd-mcp/certs:/etc/gocd-mcp/certs:ro \ -e CONFIG FILE=/etc/gocd-mcp/config.yaml \ gocd-mcp Because the file wins over the environment, you can ship a baseline config.yaml and still override a single value at runtime only for keys the file omits — keep environment-specific or sensitive values out of the file and inject them with -e e.g. from your secret store : docker run --rm -p 8443:8443 \ -v /etc/gocd-mcp/config.yaml:/etc/gocd-mcp/config.yaml:ro \ -v /etc/gocd-mcp/certs:/etc/gocd-mcp/certs:ro \ -e CONFIG FILE=/etc/gocd-mcp/config.yaml \ -e LOG LEVEL=debug \ gocd-mcp Note: the file takes priority, so a key set in config.yaml cannot be overridden by -e . Put values you want to override at runtime in the environment and omit them from the file. Env-only no file — omit CONFIG FILE and pass everything as environment variables: docker run --rm -p 8443:8443 \ -e GOCD BASE URL=https://gocd.example.com \ -e TLS CERT FILE=/certs/tls.crt -e TLS KEY FILE=/certs/tls.key \ -e TOOLSET=readonly \ -v /etc/gocd-mcp/certs:/certs:ro \ gocd-mcp Each MCP user still authenticates with their own GoCD PAT via the Authorization: Bearer header see Authentication authentication--authorization ; the container holds no GoCD credential of its own. The server can be configured from environment variables , from a YAML config file , or both. Precedence is: built-in default < environment variable < YAML file the file wins A key present in the file overrides the matching environment variable; a key omitted from the file falls back to the env var, then to the default. The file is loaded only when CONFIG FILE points at it otherwise configuration is env-only, as before . | Variable | YAML key | Description | Default | |---|---|---|---| CONFIG FILE | — | Path to a YAML config file enables file-based config | — | GOCD BASE URL | gocd base url | GoCD server root URL — required | — | LISTEN ADDR | listen addr | Address to listen on | :8443 | TLS CERT FILE | tls cert file | TLS certificate set together with key | — | TLS KEY FILE | tls key file | TLS key set together with cert | — | MCP ENDPOINT PATH | mcp endpoint path | Path of the MCP endpoint | /mcp | GOCD REQUEST TIMEOUT | gocd request timeout | Per-request timeout to GoCD | 30s | TOKEN CACHE TTL | token cache ttl | How long a validated PAT is cached | 60s | TOOLSET | toolset | readonly | actions | full | full | LOG LEVEL | log level | debug | info | warn | error | info | LOG FILE | log file | Log destination; empty → stderr, else append JSON to this file | — | GOCD BASE URL is the only required setting — the server refuses to start without it, from either source. Everything else has a working default. See config.example.yaml /Ivinco/gocd-mcp/blob/master/config.example.yaml for a fully annotated sample. Durations use Go syntax 30s , 2m , 1h .The MCP client sends the user's GoCD PAT as a bearer token on every request: Authorization: Bearer <gocd-personal-access-token The server validates the token against GoCD's current user endpoint caching the result for TOKEN CACHE TTL , then builds a per-request GoCD client bound to that token . As a result, every GoCD call is made as that user and is subject to GoCD's role-based access control. The server stores no credentials of its own. Design note.This is a deliberate, documented deviation from the OAuth 2.1 section of the MCP spec: GoCD itself is the identity provider and the PAT is the credential conceptually the stdio "credentials from the environment" model, lifted onto HTTP . A migration path to full OAuth 2.1 is kept open by isolating token verification behind a single interface. ⚠️ TLS is required in production.The PAT travels in the Authorization header. Run with TLS CERT FILE / TLS KEY FILE , or terminate TLS at a trusted proxy. The PAT is never logged. In GoCD, open your user menu → Personal Access Tokens → create a token. Each user uses their own; the token's GoCD permissions define what that user can do through this server. Read-only, TLS-enabled TLS CERT FILE=server.crt TLS KEY FILE=server.key \ GOCD BASE URL=https://gocd.example.com \ TOOLSET=readonly \ ./gocd-mcp Health checks unauthenticated : php curl -fsS https://localhost:8443/healthz - ok curl -fsS https://localhost:8443/readyz - ready 200 if GoCD is reachable Unauthenticated requests to the MCP endpoint return 401 Unauthorized . The binary is static and configuration-free by itself, so a unit is all it takes. Install it to /usr/local/bin/gocd-mcp , put a config.yaml next to your TLS material, and point CONFIG FILE at it: Unit Description=GoCD MCP server After=network-online.target Wants=network-online.target Service Type=simple Environment=CONFIG FILE=/etc/gocd-mcp/config.yaml ExecStart=/usr/local/bin/gocd-mcp Restart=always RestartSec=5s Install WantedBy=multi-user.target Set log file in the config to write JSON logs to a path rotate it with logrotate , using copytruncate — the server keeps the file open , or leave it unset to log to stderr and let journald collect it. Point the client at the Streamable HTTP endpoint and supply the GoCD PAT as a bearer token. Claude Code .mcp.json in your project, or via claude mcp add : { "mcpServers": { "gocd": { "type": "http", "url": "https://your-host:8443/mcp", "headers": { "Authorization": "Bearer ${GOCD PAT}" } } } } Claude Desktop claude desktop config.json : use the same mcpServers block with an http transport and the Authorization header. Set GOCD PAT in your environment to your GoCD Personal Access Token. TOOLSET gates which tools are registered, so you can deploy the least-privileged surface appropriate to a use case: TOOLSET | Includes | |---|---| readonly | Queries only — no state changes | actions | readonly + trigger / pause / unpause / cancel / comment | full | actions + config editing update / create / delete pipeline, update agent | A read-only deployment is useful for broad, low-risk access; full should be reserved for trusted operators GoCD RBAC still applies on top . The protocol layer is intentionally thin; all logic lives in a transport-agnostic domain layer, so the GoCD integration is independently testable. MCP client ──Streamable HTTP Bearer PAT ──▶ httpx TLS, middleware, /healthz /readyz └─ bearer-token auth validate PAT vs GoCD └─ MCP server tools / resources / prompts └─ domain validation, orchestration └─ gocd typed REST client, acts as user | Package | Responsibility | |---|---| cmd/gocd-mcp | Entry point: config → wiring → graceful shutdown | internal/config | Env-based configuration + validation | internal/httpx | net/http server, TLS, middleware recovery / request-id / access log , health probes | internal/auth | Bearer-token verification PAT → GoCD , per-request principal, validation cache | internal/mcpsrv | MCP tools/resources, argument schemas, audit logging, error mapping | internal/domain | Input validation and orchestration of GoCD calls no MCP, no net/http | internal/gocd | Typed GoCD REST client pinned API media-type versions, ETag/If-Match, error mapping | internal/obs | Structured logging slog | GoCD's API uses per-endpoint versioned media types application/vnd.go.cd.vN+json and optimistic locking ETag + If-Match for config edits; both are handled in internal/gocd . TLS required in production; the PAT is a bearer credential. Tokens are never logged — access and audit logs contain the GoCD login only. Authorization is delegated to GoCD — the server never widens a user's permissions. Audit trail — every mutating action logs action , login , and target . Least privilege — run with TOOLSET=readonly or actions where full access isn't needed. Input validation — pipeline/agent identifiers are validated before building request paths.- Destructive tools are annotated so hosts can require explicit user confirmation. Structured JSON logs slog at LOG LEVEL . Destination is LOG FILE — unset means stderr captured by Docker/journald ; a path appends JSON there rotate externally, e.g. logrotate . Tokens are never logged. Three event types: msg | When | Key fields | |---|---|---| request | every HTTP request | method , path , status , duration ms , request id , login for authenticated /mcp calls | tool call | every tool invocation reads and writes | tool , login , ok , duration ms , request id | audit | every mutating tool | action , login , target | request id correlates the request and tool call lines of the same call. Tool arguments are not logged to avoid leaking config bodies ; the audit line carries the mutation target. go test ./... unit domain , contract gocd via httptest , e2e MCP via SDK client go vet ./... gofmt -l . should print nothing go build ./... Project layout follows the package table in Architecture architecture . Tests run fully offline a fake GoCD via httptest ; no live GoCD instance is required. | Symptom | Likely cause / fix | |---|---| 401 Unauthorized on /mcp | Missing/invalid Authorization: Bearer <PAT , or GoCD rejected the token | | Tool error "your GoCD user lacks permission" | The user's GoCD RBAC does not allow the operation | | Tool error "version conflict ETag mismatch " | Config changed since you read it — re-run get pipeline config and retry | /readyz returns 503 | GoCD is unreachable from the server check GOCD BASE URL / network | | A tool isn't listed | It's gated by TOOLSET — raise the tier actions / full | GOCD BASE URL is required on startup | The base URL has no default — set it in the config file or the environment | Issues and pull requests are welcome — see CONTRIBUTING.md /Ivinco/gocd-mcp/blob/master/CONTRIBUTING.md for the build/test loop and the layering rules the codebase keeps to. Found a security problem? Please report it privately: see SECURITY.md /Ivinco/gocd-mcp/blob/master/SECURITY.md . MIT /Ivinco/gocd-mcp/blob/master/LICENSE © Ivinco