Argo Watcher MCP Server

A simple service that exposes an argo-watcher instance as a set of tools via the Model Context Protocol (MCP), allowing AI agents and other clients to query deployment history.

[!IMPORTANT] This project is currently a Proof of Concept (PoC). It was built to explore the integration between Argo Watcher and the Model Context Protocol (MCP). As such, it may be subject to significant changes or be abandoned in the future. Please use it with this understanding.

Features

• Exposes argo-watcher's read-only API as MCP tools: what was deployed, when, by whom, and whether it succeeded.
• Also surfaces the deploy lock, dependency reachability, and instance config.
• Runs over stdio or HTTP (streamable SSE) via the official MCP Go SDK.
• Multi-platform distroless container image.

[!NOTE] Read-only by design: this server cannot create deployments or change the deploy lock.

Tools

Parameters and constraints live in each tool's MCP schema. Two things it does not tell you:

• get_deployments returns 50 rows by default and 1000 at most, so check total and truncated before counting. An empty result can also mean argo-watcher's database is unreachable; get_reachability distinguishes the two.
• get_server_info forwards an allowlist of config fields, reduces oidc, webhook and mattermost to their enabled flag, and strips user:password@ from URL-valued fields — argo-watcher does not redact ARGO_URL_ALIAS or DOCKER_IMAGES_PROXY itself.

Required argo-watcher version

Older versions silently ignore unknown query parameters, so a filter can appear to apply when it did not.

v0.13.0+ is recommended; v0.14.0 is the current stable upstream release.

This server's readiness check requires argo-watcher's /livez and /readyz, which arrive with the probe split and are unreleased. Against v0.14.0 and older it reports 503 with no probe payload, so give this server an upstream that serves them before wiring a readiness probe to it. Every MCP tool works against v0.13.0+ regardless.

Prerequisites

• Go 1.26+ (for local builds and development).
• Docker 24+ (optional, for containerized deployment).
• Task 3.x (optional, to use the provided Taskfile).
• A running instance of argo-watcher.

Quickstart

1. Ensure argo-watcher is running

   The MCP server reads deployment data from an existing argo-watcher instance. You can bootstrap one quickly using the official docker-compose file.

   # In the argo-watcher repository
   docker compose up
   

2. Configure the MCP server

   Export the required environment variables:

   export ARGO_WATCHER_URL="http://localhost:8001"  # adjust to your deployment
   export HTTP_LISTEN_ADDR=":8000"
   

3. Run the server locally

   task run
   

   The process exposes:

   • Choose the transport via the TRANSPORT_MODE environment variable (stdio or http).
   • In stdio mode the server communicates over stdin/stdout; in http mode it serves a streamable endpoint on HTTP_LISTEN_ADDR (default :8000).

4. (Optional) Run via Docker

   GOOS=linux GOARCH=amd64 go build -o linux/amd64/argo-watcher-mcp ./cmd/server
   docker build --build-arg TARGETPLATFORM=linux/amd64 -t argo-watcher-mcp .
   docker run --rm -p 8000:8000 \
     -e ARGO_WATCHER_URL="http://host.docker.internal:8001" \
     argo-watcher-mcp
   

   For the real multi-platform images, use goreleaser release --snapshot --clean.

Configuration

Health endpoints

The HTTP transport serves two unauthenticated probe endpoints:

/readyz deliberately stays 200 when argo-watcher answers but reports itself unready — its state backend is down, or it is shutting down. Every replica of this server shares one argo-watcher, so failing readiness there would withdraw all of them at once and take get_reachability, the tool that names the cause, out of reach with them. That verdict is reported in the body instead:

{"status":"ready","argo_watcher":"not_ready","argo_watcher_reason":"state backend unreachable"}

Alert on get_reachability or on argo-watcher's own metrics for that condition. /readyz returns 503 only when argo-watcher's process does not answer at all — including against an upstream too old to serve /livez, per Required argo-watcher version.

Each upstream probe is bounded at 2s rather than by REQUEST_TIMEOUT, so this endpoint answers inside a normal probe deadline even when argo-watcher's readiness handler hangs on its state backend.

Telemetry & Metrics

When telemetry is enabled, the HTTP transport exposes Prometheus metrics at /metrics. Key series:

• argo_watcher_mcp_requests_total{result="success|invalid|failed"} – MCP tool call counter partitioned by result label; filter by result to obtain invalid or failed counts.
• argo_watcher_reachable – gauge reporting downstream reachability (1 when argo-watcher answered, 0 otherwise). It tracks reachability, not health: an argo-watcher whose readiness probe reports it unready still reads 1.
• Standard Go runtime (go_*) and process metrics are registered on the Prometheus endpoint to aid capacity monitoring.

Development

Common tasks are exposed via the included Taskfile:

• task test – run unit tests.
• task build – compile the server binary into bin/argo-watcher-mcp.
• task fmt – format the Go sources.
• task tidy – tidy module dependencies.
• task vet – execute go vet ./....
• task run – start the server locally using the default transport mode (stdio unless TRANSPORT_MODE is set).

Module and build caches live inside .cache/ and are ignored by git.

Releases are produced with GoReleaser and publish multi-architecture container images (linux/amd64 and linux/arm64) to GHCR when tags matching v*.*.* are pushed.

Contributing

As this is a PoC, formal contributions are not the primary focus. However, if you find a bug or have a suggestion, feel free to open an issue.