Production Argo CD MCP Server Template (TypeScript)

Overview

This template gives you a production-ready Model Context Protocol (MCP) server that bridges AI agents — such as Claude Desktop, Cursor, or Windsurf — with your Argo CD GitOps platform. Instead of copy-pasting kubectl commands or clicking through the Argo CD UI, your AI agent can query application health, sync status, Kubernetes resources, and events directly through natural language. The server wraps the official Argo CD REST API and exposes a curated set of safe, read-first tools that make day-to-day GitOps workflows faster.

The template is intentionally conservative. Read operations are enabled by default. The one write operation included — sync_application — ships with explicit validation, a dry-run guard, and prominent warnings, because pushing a sync in production is a real-world consequence. Destructive operations such as delete_application are deliberately omitted. This posture makes the server suitable for team environments where not every AI assistant session should carry full Argo CD admin rights.

Who is this for? Platform engineers, SRE teams, and developers who manage Kubernetes workloads with Argo CD and want to give their AI coding assistants real, live context about deployment state — without standing up a heavy integration or risking accidental changes to production clusters.

What You'll Learn

• How to scaffold a TypeScript MCP server using the official @modelcontextprotocol/sdk package with Streamable HTTP transport
• How to protect an MCP endpoint with API key authentication middleware in Express
• How to call an authenticated upstream REST API (Argo CD) from MCP tool handlers with proper token hygiene
• How to define and validate MCP tool input schemas using Zod and convert them to JSON Schema for the SDK
• How to implement structured JSON logging with Pino, including request correlation IDs and configurable log levels
• How to apply express-rate-limit to an MCP HTTP endpoint and return correct 429 responses
• How to write a /health endpoint that checks upstream API reachability and returns machine-readable JSON status
• How to write Jest + Supertest integration tests that cover auth rejection, health checks, and tool execution
• How to build a multi-stage Docker image that produces a lean production container from a TypeScript source tree
• How to wire up a GitHub Actions CI pipeline with lint, type-check, test, and Docker build steps
• How to manage secrets safely: never logging tokens, never returning them in tool responses, using least-privilege Argo CD tokens
• How to configure MCP clients (Claude Desktop, Cursor, Windsurf, Continue) to talk to a self-hosted HTTP MCP server

Architecture

AI Agent (Claude / Cursor / Windsurf)
        │
        │  HTTP POST /mcp  (Bearer API Key)
        ▼
┌─────────────────────────────────────────┐
│           Express Application           │
│                                         │
│  Rate Limiter → Auth Middleware         │
│        │                                │
│        ▼                                │
│  MCP Streamable HTTP Transport          │
│        │                                │
│        ▼                                │
│  MCP Server (Tool Router)               │
│    ├── list_applications                │
│    ├── get_application                  │
│    ├── get_application_health           │
│    ├── get_application_sync_status      │
│    ├── list_application_resources       │
│    ├── get_application_events           │
│    ├── refresh_application              │
│    └── sync_application  ⚠️ write       │
│        │                                │
│  Argo CD API Client                     │
└────────────┬────────────────────────────┘
             │  HTTPS + Argo CD API Token
             ▼
      Argo CD Server (REST API)
             │
             ▼
    Kubernetes Cluster(s)

Project Structure

argo-cd-mcp-server/
├── .env.example
├── .gitignore
├── eslint.config.js
├── package.json
├── tsconfig.json
├── tsconfig.eslint.json
└── src/
    ├── server.ts
    ├── config.ts
    ├── logger.ts
    ├── auth.ts
    ├── health.ts
    ├── __tests__/
    │   └── auth.test.ts
    ├── argocd/
    │   ├── types.ts
    │   └── client.ts
    └── tools/
        ├── index.ts
        ├── listApplications.ts
        ├── getApplication.ts
        ├── getApplicationHealth.ts
        ├── getApplicationSyncStatus.ts
        ├── listApplicationResources.ts
        ├── getApplicationEvents.ts
        ├── refreshApplication.ts
        └── syncApplication.ts

Prerequisites

• Node.js 20 or later
• npm 10 or later
• A running Argo CD instance (v2.8+) with network access from this server
• An Argo CD API token (see Argo CD Token Setup section in the README)
• Docker (optional, for containerised deployment)

Quick Start

# 1. Clone / copy the template
git clone https://github.com/your-org/argo-cd-mcp-server.git
cd argo-cd-mcp-server

# 2. Install dependencies
npm install

# 3. Configure environment
cp .env.example .env
# Edit .env — set ARGOCD_SERVER_URL, ARGOCD_TOKEN, MCP_API_KEY

# 4. Build TypeScript
npm run build

# 5. Start the server
npm start

# 6. Verify health
curl http://localhost:3000/health

# 7. Run tests
npm test

Features

• Streamable HTTP transport — compatible with all MCP clients that support HTTP-based servers
• API key auth — every request to /mcp must carry a valid Authorization: Bearer <key> header
• Argo CD REST API client — typed, reusable client with token injection and TLS options
• 8 Argo CD tools — list apps, get app detail, health, sync status, resources, events, refresh, and (opt-in) sync
• Zod input validation — all tool inputs are validated before any upstream API call is made
• Pino structured logging — JSON output with correlation IDs, redacted secrets, configurable LOG_LEVEL
• Rate limiting — configurable via RATE_LIMIT_WINDOW_MS and RATE_LIMIT_MAX
• Health endpoint — GET /health checks Argo CD API reachability, returns structured JSON
• Multi-stage Dockerfile — builder stage compiles TypeScript; production stage runs only dist/
• docker-compose.yml — one-command local stack
• Jest + Supertest tests — covers health, auth rejection, and tool execution
• GitHub Actions CI — lint, type-check, test, and Docker build on every push

Works With

• Claude Desktop — add server to claude_desktop_config.json under mcpServers
• Claude Code — use claude mcp add with --transport http
• Cursor — add under Settings → MCP → Add Server
• Windsurf — configure in mcp_config.json
• Continue — add as an MCP provider in config.json

Example Claude Desktop configuration

{
  "mcpServers": {
    "argocd": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:3000/mcp"],
      "env": {
        "MCP_REMOTE_HEADER_AUTHORIZATION": "Bearer your-mcp-api-key"
      }
    }
  }
}

Configuration

Deployment

Docker (recommended)

# Build
docker build -t argo-cd-mcp-server:latest .

# Run
docker run -d \
  --name argo-cd-mcp \
  -p 3000:3000 \
  --env-file .env \
  argo-cd-mcp-server:latest

Docker Compose (local dev)

docker compose up --build

Railway

npm install -g @railway/cli
railway login
railway new
railway up
# Set env vars in the Railway dashboard

Fly.io

npm install -g flyctl
fly launch --name argo-cd-mcp-server
fly secrets set MCP_API_KEY=xxx ARGOCD_TOKEN=yyy ARGOCD_SERVER_URL=https://argocd.example.com
fly deploy

Argo CD Token Setup

1. Log in to Argo CD: argocd login argocd.example.com
2. Create a dedicated service account: argocd account create mcp-server
3. Grant read-only RBAC in argocd-rbac-cm ConfigMap:

policy.csv: |
  p, role:mcp-readonly, applications, get, */*, allow
  p, role:mcp-readonly, applications, list, */*, allow
  p, role:mcp-readonly, clusters, get, *, allow
  g, mcp-server, role:mcp-readonly

1. If you need sync, add the sync action to the role:

  p, role:mcp-readonly, applications, sync, */*, allow

1. Generate the token: argocd account generate-token --account mcp-server
2. Copy the token value into ARGOCD_TOKEN in your .env.

⚠️ Never commit the token. Use environment variables or a secrets manager.

Production Checklist

• MCP_API_KEY is a strong random value (32+ chars), stored in a secrets manager
• ARGOCD_TOKEN is scoped to the minimum required RBAC permissions
• ARGOCD_INSECURE_TLS is false in production
• ENABLE_SYNC_TOOL is false unless your team has reviewed the sync workflow
• LOG_LEVEL is info or warn in production (not debug or trace)
• Rate limiting values are tuned for your expected agent call volume
• The container runs as a non-root user (the Dockerfile enforces this)
• Health endpoint is wired up to your load balancer / Kubernetes liveness probe
• TLS is terminated at the ingress layer — do not expose port 3000 directly
• GitHub Actions CI passes on the main branch before any deploy
• Docker image is scanned for CVEs before pushing to production
• Logs are shipped to a centralised log aggregator (Datadog, Loki, etc.)
• Argo CD token rotation procedure is documented and scheduled
• NODE_ENV=production is set so stack traces are not leaked in error responses
• Resource limits (CPU/memory) are set on the Kubernetes Deployment or Docker container

Testing

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Manual health check
curl http://localhost:3000/health

# Manual MCP call — list applications
curl -X POST http://localhost:3000/mcp \
  -H "Authorization: Bearer your-mcp-api-key" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_applications","arguments":{}}}'

Troubleshooting

Further Reading

• MCPForge Argo CD MCP Server Guide
• Model Context Protocol TypeScript SDK
• Argo CD REST API Reference
• Argo CD RBAC Configuration