Connect Argo CD to Claude: Control Clusters, Projects & Repositories

If your team uses ChatGPT, check out our guide on connecting Argo CD to ChatGPT or explore our broader architectural overview on connecting Argo CD to AI Agents.

Platform engineering teams manage hundreds of microservices, namespaces, and Kubernetes clusters using Argo CD. Giving a Large Language Model (LLM) read and write access to your GitOps control plane changes how you handle incident response and release management. Instead of clicking through the Argo UI to figure out why an application is out of sync, fetching logs manually, and checking cluster status, you can ask Claude to investigate the health status and trigger a sync for you.

To achieve this, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's tool calls and Argo CD's REST API. You can either build and maintain this infrastructure yourself, dealing with protobuf schemas and gRPC wrappers, or use a managed integration platform like Truto to dynamically generate a secure, authenticated MCP server URL.

This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for Argo CD, connect it natively to Claude, and execute complex continuous delivery workflows using natural language.

The Engineering Reality of the Argo CD API

A custom MCP server is a self-hosted integration layer. While the open MCP standard provides a predictable way for models to discover tools, the reality of implementing it against Argo CD's API requires dealing with severe architectural quirks.

If you decide to build a custom MCP server for Argo CD, you own the entire API lifecycle. You are not just integrating a standard REST API - you are integrating a system designed for declarative GitOps that exposes a REST wrapper over a gRPC backend. Here are the specific challenges you will face:

gRPC-Gateway Schema Complexities

Argo CD's REST API is generated via grpc-gateway. This means the JSON payloads often mirror protobuf structures, which can be highly nested and unforgiving. For example, updating an application requires passing a deep v1alpha1.Application spec object. If you expose this raw schema to Claude without curation, the model will frequently hallucinate missing required protobuf fields (like omitting project or misformatting the destination block). You have to manually map and simplify these JSON schemas into MCP tool definitions that an LLM can understand and reliably construct.

Asynchronous Sync Operations

Argo CD operations are rarely synchronous. When you tell Argo CD to sync an application, the API returns a status object immediately, but the actual deployment happens asynchronously on the Kubernetes cluster. To know if a deployment succeeded, your AI agent has to continually poll the status.operationState.phase endpoint. If you do not build state-checking tools, Claude will trigger a sync, immediately assume it succeeded, and confidently report false information to the user.

Strict RBAC and Project Scoping

Argo CD enforces strict Role-Based Access Control (RBAC) at the project level. An API token might have permission to read applications in the default project but not in the infrastructure project. When Claude attempts to access a restricted resource, Argo CD often returns cryptic 403 Forbidden errors. Your MCP server needs to gracefully catch these permission boundaries and return clear, actionable error text to the LLM so it knows why the operation failed, rather than getting stuck in a retry loop.

Standardizing Rate Limits

When operating against an Argo CD instance (especially managed or highly active instances), aggressive polling or mass updates will trigger rate limits. Truto does not retry, throttle, or apply backoff on rate limit errors. When the upstream Argo CD API returns an HTTP 429 error, Truto passes that error directly to the caller. Truto normalizes the upstream rate limit info into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF spec. The caller - in this case, the Claude client or the custom AI agent - is completely responsible for implementing its own retry and backoff logic.

How to Generate an Argo CD MCP Server with Truto

Truto dynamically generates MCP tools based on the actual endpoints available in your connected Argo CD instance. Authentication, API routing, and schema extraction are handled for you.

You can generate an Argo CD MCP server using either the Truto UI or the API.

Method 1: Via the Truto UI

1. Log in to your Truto dashboard and navigate to the integrated account page for your Argo CD connection.
2. Click the MCP Servers tab.
3. Click Create MCP Server.
4. Select your desired configuration. You can assign a human-readable name, restrict allowed methods (e.g., read-only), apply tag filters, and set an expiration date.
5. Click Create and copy the generated MCP server URL (e.g., https://api.truto.one/mcp/a1b2c3d4e5f6...).

Method 2: Via the Truto API

For automated provisioning, you can generate an MCP server programmatically. Truto validates the connection, provisions the token, stores it securely, and returns a ready-to-use URL.

Make a POST request to /integrated-account/:id/mcp:

curl -X POST https://api.truto.one/integrated-account/<ARGO_CD_ACCOUNT_ID>/mcp \
  -H "Authorization: Bearer <YOUR_TRUTO_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Argo CD DevOps Assistant",
    "config": {
      "methods": ["read", "write"]
    },
    "expires_at": "2026-12-31T23:59:59Z"
  }'

The API returns a payload containing the secure URL:

{
  "id": "abc-123",
  "name": "Argo CD DevOps Assistant",
  "config": { "methods": ["read", "write"] },
  "expires_at": "2026-12-31T23:59:59.000Z",
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f6..."
}

Connecting the MCP Server to Claude

Once you have the Truto MCP URL, connecting it to Claude requires no custom code. The URL itself acts as the secure transport and authentication layer.

Method A: Via the Claude or ChatGPT UI

If you are using a web client that supports direct MCP integrations (like Claude for Enterprise/Team or ChatGPT with Developer Mode):

1. In your LLM interface, navigate to Settings -> Connectors (or Settings -> Integrations -> Add MCP Server).
2. Click Add custom connector.
3. Paste your Truto MCP server URL.
4. Click Add. The client will automatically initialize the connection, perform the JSON-RPC handshake, and load the Argo CD tools.

Method B: Via Claude Desktop Configuration

To connect Claude Desktop to your Argo CD instance, you will update the local claude_desktop_config.json file. Truto MCP servers operate over SSE (Server-Sent Events), so you will use the official @modelcontextprotocol/server-sse proxy to connect.

Open your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the Argo CD server block:

{
  "mcpServers": {
    "argocd": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "https://api.truto.one/mcp/a1b2c3d4e5f6..."
      ]
    }
  }
}

Restart Claude Desktop. The application will fetch the tools and they will be immediately available in your prompt interface.

Argo CD Hero Tools for Claude

Once connected, Claude has access to Argo CD's operational surface. Truto normalizes the complex gRPC-gateway JSON schemas into flat, LLM-friendly schemas.

Here are the highest-leverage tools your AI agent can use to control your GitOps environment.

1. list_all_argo_cd_applications

This is the primary discovery tool. It allows Claude to fetch all managed applications across your clusters, inspect their sync status, and determine overall health. The schema normalizes pagination, enabling Claude to safely iterate through large enterprise catalogs.

"List all Argo CD applications. Filter for any applications that currently have a Degraded health status or an OutOfSync state, and give me a summary of which projects they belong to."

2. get_single_argo_cd_application_by_id

When investigating a specific failure, Claude needs deep context. This tool retrieves the complete metadata, spec, and operational state of a single application. It exposes exactly which Git repository, revision, and path the application is tracking, alongside the detailed health assessment.

"Get the details for the Argo CD application named 'payment-service-prod'. I need to see the exact target revision it is tracking and what the most recent sync operation state is."

3. create_a_argo_cd_application_sync

This tool allows Claude to take action by triggering a sync to reconcile the application state with the target Git repository. It is essential for automating release pipelines or fixing configuration drift.

"Trigger a sync for the 'inventory-api-staging' application. The PR just merged, so we need Argo to pull the latest manifests and reconcile the cluster state immediately."

4. update_a_argo_cd_application_spec_by_id

Instead of just syncing, Claude can mutate the application spec directly. This tool is used to change the target revision (e.g., pinning to a new release tag) or update Helm parameter overrides without leaving the chat interface.

"Update the application spec for 'frontend-app-qa'. Change the target revision from 'v1.4.2' to 'v1.4.3' so we can test the new hotfix."

5. create_a_argo_cd_application_rollback

When a deployment fails, speed is critical. This tool instructs Argo CD to revert the application to a previously known good state. Claude can use this in combination with application history lookups to identify safe revisions and execute the rollback.

"The current sync for 'auth-service-prod' is failing health checks. Execute a rollback to the immediate previous successful revision to restore service stability."

6. list_all_argo_cd_clusters

Argo CD operates across fleets of Kubernetes clusters. This tool provides visibility into the connected infrastructure, allowing Claude to check connection states, server addresses, and cluster labels. It is highly useful for infrastructure auditing.

"List all clusters connected to this Argo CD instance. Tell me if any of the cluster connection states are marked as 'Failed' or 'Unknown'."

To view the complete list of available operations, required fields, and JSON schemas, visit the Argo CD integration page.

Workflows in Action

Connecting tools is only the first step. The real value of an MCP server is enabling complex, multi-step agentic workflows where Claude autonomously retrieves data, makes decisions, and executes operations.

Workflow 1: Investigating and Remediating a Degraded Application

When an alert fires indicating a service is down, DevOps engineers usually have to log into Argo CD, find the app, check the health tree, and trigger a sync. Claude automates this entirely.

"Check the status of the 'billing-worker' application. If it is OutOfSync or Degraded, tell me why, and then trigger a sync to reconcile it."

sequenceDiagram
    participant User as User
    participant Claude as Claude
    participant MCP as MCP Server
    participant Argo as Argo CD API
    
    User->>Claude: "Check billing-worker and sync if needed."
    Claude->>MCP: Call get_single_argo_cd_application_by_id
    MCP->>Argo: GET /api/v1/applications/billing-worker
    Argo-->>MCP: Returns spec and OutOfSync status
    MCP-->>Claude: Application data
    Claude->>MCP: Call create_a_argo_cd_application_sync
    MCP->>Argo: POST /api/v1/applications/billing-worker/sync
    Argo-->>MCP: Returns Sync Operation State
    MCP-->>Claude: Sync triggered confirmation
    Claude-->>User: "The app was OutOfSync. I have triggered a sync operation."

Step-by-step execution:

1. Claude calls get_single_argo_cd_application_by_id with id: "billing-worker".
2. It parses the JSON response, specifically looking at status.sync.status and status.health.status.
3. Upon detecting the application has drifted, Claude autonomously calls create_a_argo_cd_application_sync.
4. Claude returns a natural language summary confirming the sync was initiated.

Workflow 2: Automated Rollback on Failed Deployments

If a new release causes a crash loop backoff in Kubernetes, Argo CD will report a failed health status. Claude can be instructed to investigate the failure and immediately execute a rollback.

"The deployment for 'checkout-service' just failed. Review its current state, and if the health is Degraded, execute a rollback to the previous revision."

Step-by-step execution:

1. Claude calls get_single_argo_cd_application_by_id to verify the Degraded status and inspect status.history to find the ID of the previous successful sync.
2. Claude calls create_a_argo_cd_application_rollback passing the name of the app.
3. Claude calls get_single_argo_cd_application_by_id a second time to verify the operation state transitions to the rollback process.
4. The user receives a message confirming the service is reverting to the previous git SHA.

Workflow 3: Infrastructure Auditing

Platform teams often need quick reporting on the state of their infrastructure fleet without context-switching to the Argo CD dashboard.

"Audit our Argo CD infrastructure. List all connected clusters and then list all configured repositories. Tell me if any clusters have connection errors or if any repositories have invalid credentials."

Step-by-step execution:

1. Claude calls list_all_argo_cd_clusters to pull the fleet data, checking connectionState.status.
2. Claude calls list_all_argo_cd_repositories to verify git access states.
3. Claude formats a clean Markdown report summarizing the infrastructure health, saving the platform engineer 15 minutes of UI clicks.

Security and Access Control

Giving an LLM direct API access to your continuous delivery system requires strict governance. Truto MCP servers provide multiple layers of security to ensure Claude cannot accidentally destroy your infrastructure.

• Method Filtering: Enforce read-only access by creating the server with config.methods: ["read"]. This allows Claude to use list and get operations to investigate incidents, but physically blocks it from calling create, update, or delete methods (like syncs or rollbacks).
• Tag Filtering: Restrict the server to specific operational domains. By applying tag filters during creation, you can isolate the server to only expose tools related to applications, preventing the model from tampering with clusters or repositories.
• Require API Token Auth: By default, possessing the MCP URL grants access. For enterprise environments, setting require_api_token_auth: true forces the client to also pass a valid Truto API token as a Bearer header. This means the MCP URL alone is useless without valid secondary credentials.
• Time-to-Live (TTL) Expiration: For temporary incident response, use the expires_at field. Truto schedules automated alarms that permanently destroy the MCP server credentials at the exact expiration time, ensuring no stale integration access remains after the incident is resolved.

Automating GitOps with AI

Integrating Claude directly into your Argo CD control plane eliminates the friction between natural language intent and operational execution. By utilizing a managed MCP server, platform engineering teams can bypass the boilerplate of building custom gRPC translation layers, handling pagination schemas, and mapping complex nested objects.

With Truto handling the protocol routing, your focus shifts from maintaining integration infrastructure to actually automating your deployments, orchestrating rollbacks, and giving your developers a conversational interface to their continuous delivery pipelines.