argocd-mcp: Driving Argo CD From an AI Assistant Over MCP

The gap argocd-mcp fills between Argo CD and an assistant

Argo CD already has a UI, a CLI and a REST API. What it does not have is a way for a conversational agent to discover what operations are available and call them with structured arguments. argocd-mcp supplies exactly that layer. It is a Model Context Protocol server, written in TypeScript, published on npm as argocd-mcp, and maintained under the argoproj-labs organisation rather than in the main Argo CD repository.

The audience is narrow and specific: platform or delivery engineers who already have an Argo CD instance with API access, and who work inside an MCP-capable client such as Cursor, VS Code or Claude Desktop. The README frames the goal as letting AI assistants interact with Argo CD applications through natural language.

That framing matters, because the server does not replace Argo CD's own reconciliation. It does not watch Git, compare desired and live state, or decide when an application is out of sync. Argo CD keeps doing all of that. The MCP server is a translation surface: it turns Argo CD API operations into named tools with typed parameters, so a model can choose one and fill in the arguments.

The tool surface: clusters, projects, applications, resources

The README lists the tools the server exposes, and the grouping tells you where the design effort went. Cluster management is thin: a single `list_clusters` tool. Project management is also thin: `get_appproject` retrieves one AppProject. The weight sits in application and resource management.

On the application side the tools are `list_applications`, `get_application`, `create_application`, `update_application`, `delete_application` and `sync_application`. On the resource side they are `get_application_resource_tree`, `get_application_managed_resources`, `get_application_workload_logs`, `get_resource_events`, `get_resource_actions` and `run_resource_action`.

Read that list carefully, because it defines both the capability and the risk. Write operations are present: create, update, delete, sync and run an action. An assistant wired to this server is not limited to reading state. The README describes the tools; it does not describe a confirmation step, a dry-run mode or a policy layer that gates destructive calls. If you connect it, the model's choice of tool is the only thing standing between a conversation and a deleted application. That is a design decision, not a bug, but it should shape how you deploy it.

The resource-oriented tools are the more interesting half. `get_application_workload_logs` reaches into Pods and Deployments, and `get_resource_events` pulls events for managed resources. Those turn the assistant into a debugging surface: ask why a workload is failing, and the model can pull logs and events for the same application in one exchange rather than you switching between kubectl and the Argo CD UI.

Installing argocd-mcp and making a first real call

The README's prerequisites are Node.js (v18 or higher recommended), pnpm for development, a reachable Argo CD instance with API access, and an Argo CD API token. The token is the part people underestimate; the README links to the Argo CD API documentation for how to obtain one.

The simplest path is npx, which pulls the published package and runs the stdio transport. For Cursor, the README gives a `.cursor/mcp.json` file in your project:

{
  "mcpServers": {
    "argocd-mcp": {
      "command": "npx",
      "args": ["argocd-mcp@latest", "stdio"],
      "env": {
        "ARGOCD_BASE_URL": "<argocd_url>",
        "ARGOCD_API_TOKEN": "<argocd_token>"
      }
    }
  }
}

Replace the two placeholders with your Argo CD base URL and a token. After saving, restart the client so it picks up the server, then open an agent conversation. The README says to start a conversation with Agent mode to use the MCP.

VS Code uses the same command and arguments but a different file, `.vscode/mcp.json`, and a different top-level key. Note the `"type": "stdio"` field, which the Cursor example does not carry:

{
  "servers": {
    "argocd-mcp-stdio": {
      "type": "stdio",
      "command": "npx",
      "args": ["argocd-mcp@latest", "stdio"],
      "env": {
        "ARGOCD_BASE_URL": "<argocd_url>",
        "ARGOCD_API_TOKEN": "<argocd_token>"
      }
    }
  }
}

Claude Desktop follows the same shape with `mcpServers` and a `claude_desktop_config.json` file, which you then point Claude Desktop at in its settings.

If you prefer to run the server yourself rather than let a client spawn it, the Makefile builds and starts the HTTP transport on port 3000 by default. Credentials come from the environment, so pass them on the command line:

make run ARGOCD_BASE_URL=... ARGOCD_API_TOKEN=...

For live reload during development, `make dev` runs the server from source over HTTP, and the Makefile allows a `PORT` override, for example `make run PORT=4000`.

Once connected, a first useful call is a read. Ask the assistant to list your applications, or to fetch the resource tree for one of them. If the server is configured correctly you get structured Argo CD data back; if the token is wrong or the base URL is unreachable, the tool call fails rather than silently returning an empty list.

Where the Argo CD token is allowed to live

The README is unusually explicit here, and it is the most important paragraph in the document. The Argo CD API token is treated as a secret that is only ever read from the transport layer, never from a tool-call argument. Two sources are accepted: the HTTP header `x-argocd-api-token`, which applies to the HTTP transport only, and the environment variable `ARGOCD_API_TOKEN`, which applies to all transports.

The reasoning given is that the token is outbound only. It authenticates this server to Argo CD and never authorizes an inbound caller. Those are separate concerns, and conflating them is a common mistake when people expose an MCP server beyond their own machine.

The README also refers to this as the default token, which implies a token registry exists as an alternative. The Makefile confirms it, mentioning `ARGOCD_TOKEN_REGISTRY_PATH` alongside `ARGOCD_API_TOKEN` and `ARGOCD_BASE_URL` as ways to configure a local run. The registry mechanism is not described in the portion of the README available here, so treat it as something to read up on before relying on it.

There is a second credential-related setting worth flagging. If your Argo CD instance uses a self-signed certificate or one from a private CA, the README suggests adding `NODE_TLS_REJECT_UNAUTHORIZED` set to `0`. The README attaches a warning to this: disabling SSL verification reduces security, and the setting should be used only in development environments or when you understand the implications. That is a blunt instrument. It turns off certificate validation for the whole Node.js process, not just for the Argo CD connection, so if the same process talks to anything else over TLS, that traffic loses validation too.

Network exposure, the Dockerfile defaults, and what the README does not settle

The Dockerfile is instructive because it encodes a security posture that the README only gestures at. It exposes port 3000, sets `USER 1000`, and deliberately does not set `MCP_BIND_ADDRESS`. A comment in the file explains the omission: the image keeps the loopback default, which a sidecar or another container sharing the network namespace can reach, while publishing a port is the case that needs a wider bind and stays an explicit `-e MCP_BIND_ADDRESS=0.0.0.0` alongside an inbound credential.

That is a sensible default. A container that binds to loopback cannot be reached from outside its namespace, so the failure mode of forgetting to configure authentication is contained. The moment you publish the port, you own the decision.

The build itself carries a non-obvious constraint. The Dockerfile runs the build stage with `--platform=$BUILDPLATFORM` rather than the target platform, and the comment explains why: tsup and esbuild ship a Go binary that crashes under QEMU emulation when cross-building. The output is plain, architecture-independent JavaScript, so copying it into a target-architecture final image is safe. If you maintain your own multi-arch build, that detail will save you an afternoon.

The Dockerfile also splits the entrypoint, so `docker run <image> http --stateless` replaces only the arguments and not the interpreter.

What the README does not settle is how the HTTP transport authenticates inbound callers. The token discussion is framed entirely around the server authenticating itself to Argo CD, and the Dockerfile comment refers to an inbound credential without naming it. If you plan to run the HTTP transport somewhere other than your own machine, that is the gap to close first.

The limitations that decide whether this fits

The version number is the first thing to notice. The latest release is v0.9.0, published on 2026-08-11, following v0.8.0 and v0.7.0. A sub-1.0 version under an labs organisation means the interface can move. The last push to the default branch was on 2026-08-11, the same day as the v0.9.0 release, so the repository is not dormant, but pre-1.0 software carries no compatibility promise. Pinning `argocd-mcp@latest` in a client config, as every README example does, means you accept whatever ships next.

Second, the write tools are unguarded. There is no documented confirmation prompt, approval step or scope restriction that prevents an assistant from calling `delete_application` or `run_resource_action`. The only lever the README describes is the Argo CD token's own permissions. If you want the assistant to read but not mutate, the token is where you enforce it, not the MCP server.

Third, this is the wrong tool if you need a stable automation interface. Argo CD already has a declarative GitOps model and a CLI; a pipeline that syncs applications should use those, not a natural-language layer whose tool selection is probabilistic. argocd-mcp is for interactive exploration and debugging, not for scheduled or event-driven delivery.

Finally, the credential model is a real constraint. The server needs a long-lived Argo CD API token in an environment variable or an HTTP header. If your organisation issues short-lived tokens, or forbids placing them in a client config file, the stdio setup shown in the README will not fit without changes the README does not describe.

How this differs from the Argo CD CLI and from general Kubernetes MCP servers

The obvious alternative is the Argo CD CLI. The difference is the interface contract. The CLI is a command-line program with flags and subcommands, designed for humans and scripts that know in advance what they want to do. argocd-mcp exposes the same domain as named tools with structured schemas, which is what lets a model decide at runtime which operation applies. If you already know the command, the CLI is faster and has no token-in-config problem. If you want the assistant to figure out which call to make, the CLI gives it nothing to reason over.

A second alternative is a general-purpose Kubernetes MCP server. Those operate at the cluster API level: Pods, Deployments, Services, custom resources. argocd-mcp operates at the Argo CD level, so it understands applications, AppProjects, sync status, managed resources and the resource tree. Asking a Kubernetes-level server about an Argo CD application means reconstructing Argo CD's model from raw resources, including the labels and annotations Argo CD uses to track ownership. Asking argocd-mcp means the model gets the application object directly. The trade-off runs the other way too: a Kubernetes-level server can reach resources Argo CD does not manage, and argocd-mcp cannot.

A third option is to skip MCP and call the Argo CD REST API from your own tooling. That gives you full control over authentication, retries and audit logging, at the cost of writing and maintaining the integration yourself. argocd-mcp is the shortcut; the REST API is the long road with fewer surprises.

Licence, upgrade cost and what the repository layout tells you

The project is licensed under Apache-2.0, and the LICENSE file sits at the repository root. Apache-2.0 permits commercial use, modification and redistribution, and includes an express grant of patent rights plus a patent retaliation clause. It also requires that you preserve copyright and licence notices and state significant changes. The package.json declares the same licence. None of this is legal advice; if you are embedding the server in a product, have counsel read the licence rather than this paragraph.

Upgrade cost is driven by the pre-1.0 status and the pinned `@latest` tag. Because the README's own examples resolve the newest version on every client start, an upgrade can arrive without you changing anything. The tool list is the surface that matters: if a future release renames `sync_application` or changes its arguments, an assistant that learned the old schema will start failing tool calls. Pinning an explicit version in your client config is the way to make upgrades deliberate, and it is a change you make in `.cursor/mcp.json`, `.vscode/mcp.json` or `claude_desktop_config.json`, not in the server.

The repository layout is small and conventional for a TypeScript CLI: `src/` for source, `tsup.config.ts` for the bundler, `dtsgen.json` for generating Argo CD types from a Swagger definition, `eslint.config.mjs` and `.prettierrc` for linting and formatting, a Makefile with a documented `help` default goal, and a SECURITY.md. The presence of `pnpm-workspace.yaml` and both `package-lock.json` and `pnpm-lock.yaml` suggests the project has moved between package managers; the Makefile and Dockerfile both standardise on pnpm, and package.json declares `[email protected]`.

There is no documented migration guide, no changelog in the README, and no statement about how breaking changes are handled. For a sub-1.0 tool used interactively, that is tolerable. For anything you depend on, it is the reason to pin.

Editorial conclusion

Adopt argocd-mcp if you already run Argo CD with API access and want an assistant to read application state, pull workload logs and trigger syncs without leaving the editor. Skip it if you need a supported, stable interface for automated pipelines, or if you cannot hand a long-lived Argo CD API token to a locally spawned process. Before wiring it into anything shared, confirm which credential mode you are using, check whether your Argo CD endpoint presents a certificate your system store trusts, and decide explicitly whether the listener stays on the loopback default or is published with a bind address and an inbound credential.

Frequently asked questions

Official sources

1. argoproj-labs/mcp-for-argocd on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases