gocd-mcp

A production-grade Model Context Protocol (MCP) server that exposes GoCD 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)

Table of contents

• Features
• Tools & resources
• Requirements
• Installation
• Configuration
• Authentication & authorization
• Running the server
• Connecting an MCP client
• Toolsets (risk tiers)
• Architecture
• Security
• Logging & observability
• Development
• Troubleshooting
• Contributing
• License

Features

• 🔐 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.

Tools & resources

Mutating tools carry MCP annotations (destructiveHint / idempotentHint) so the host can ask for user confirmation before running them.

Tools

Resources

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

Requirements

• 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)

Installation

With go install

go install github.com/ivinco/gocd-mcp/cmd/gocd-mcp@latest   # -> $GOBIN/gocd-mcp

From source

git clone https://github.com/ivinco/gocd-mcp.git
cd gocd-mcp
go build -o gocd-mcp ./cmd/gocd-mcp

Docker

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) 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); the container holds no GoCD credential of its own.

Configuration

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).

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 for a fully annotated sample. Durations use Go syntax (30s, 2m, 1h).

Authentication & authorization

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.

Generating a GoCD Personal Access Token

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.

Running the 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):

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.

As a systemd service

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.

Connecting an MCP client

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.

Toolsets (risk tiers)

TOOLSET gates which tools are registered, so you can deploy the least-privileged surface appropriate to a use case:

A read-only deployment is useful for broad, low-risk access; full should be reserved for trusted operators (GoCD RBAC still applies on top).

Architecture

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)

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.

Security

• 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.

Logging & observability

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:

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.

Development

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. Tests run fully offline (a fake GoCD via httptest); no live GoCD instance is required.

Troubleshooting

Contributing

Issues and pull requests are welcome — see 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.

License

MIT © Ivinco