Getting Started with the Akuity Agentic Control Plane & MCP Server
Jiacheng Xu
Managing applications across several environments often starts with a simple question: which version is running where? Answering it can mean checking multiple Argo CD instances, comparing container images, and reviewing Kargo promotion history. If an application is unhealthy, you also need to understand what changed before deciding how to respond.
The Akuity Agentic Control Plane makes that delivery context available to your AI agents and lets your organization control what they can change. External agents connect through the Akuity MCP Server, which provides access to enabled Argo CD and Kargo instances and fleet information through one platform connection.
In this walkthrough, we'll connect an agent, inspect the fleet with read-only access, and see how Akuity handles a request to change an application. We'll also use the Akuity agent plugin to bring the On-call Agent into an investigation.
Connect Your Agent to Akuity
Before you begin
This walkthrough uses applications your team already manages, so setup is mostly confirming access. Check that you have the following before you start:
An Akuity Cloud organization with MCP Early Access enabled
An existing Argo CD instance with applications your team already manages
A supported MCP client; we'll use Claude Code here; the agent-plugins repository also covers Codex.
Permissions you’ll need
Every inspection step works with read-only access. Enabling MCP access in the first place needs organization-level rights.
Instance update permission to enable access for a given instance
Read-only access is enough for every inspection step. The sync example later on is optional.
Organization Owner, or Organization update permission, to enable the platform endpoint and configure guardrails.
Two steps depend on services your team may not run: Kargo history requires Kargo, and the native-agent example requires the corresponding Akuity services to be enabled. We'll discover your instances and applications first, then use those names in the requests that follow.
Enable MCP Access and Install the Plugin
Open the Connect AI agents page under Organization Settings → MCP Access. On Endpoints, enable the platform endpoint, select the instances the agent should access, and click Save. On Guardrails, confirm Read-only is selected and save any changes.
Figure 1: The Endpoints tab provides the platform connection details. The plugin below configures that connection for you.
The optional Akuity agent plugin packages the MCP connection with maintained workflow skills. In Claude Code, install it with:
/plugin marketplace add akuity/agent-plugins
/plugin install akuity@akuity
The default connection uses https://akuity.cloud/mcp. For an EU organization, after adding the marketplace, install from your shell with the EU endpoint instead:
claude plugin install akuity@akuity --config endpoint=https://eu.akuity.cloud/mcp
Run /mcp, select akuity, and authenticate in your browser.
The platform connection uses your Akuity organization permissions and reaches the enabled instances you're allowed to access. Users who authenticate directly with Argo CD or Kargo can use an instance endpoint with native authentication and RBAC. Those connection options are documented separately.
Why the tools and the skills ship separately
An MCP tool describes a single operation and its inputs. A real workflow needs more than that: ordering and knowledge of how the platform behaves. Creating an application through the platform endpoint, for example, means waiting for an Argo CD instance to become healthy before the next resource can be applied.
The plugin's skills carry that sequencing, which is why the tools and the skills ship separately: you can call the MCP server directly for ad-hoc questions, run Akuity's maintained workflows, or write your own skills that encode your team's delivery standards. The skills that ship with the plugin are published in the agent-plugins repository.
Set Guardrails for Agent Access
An engineer may need permission to change production while the organization is still evaluating how agents should participate. Akuity lets you narrow MCP access without changing that engineer's normal access through the portal, API, or CLI.
The organization has three cumulative guardrail levels:
Level | What it allows |
|---|---|
Read-only | Inspect applications, resources, events, available logs, and delivery history. This is the default. |
Read & write | Add operations such as sync, refresh, rollback, promotion, restart, manifest application, and starting native-agent conversations. |
Full | Also allows operations such as deletion, resource patching, instance-spec application, and approval of native-agent tool actions. |
The level applies across the organization's platform and direct instance endpoints. It limits which MCP operations are permitted; every request must also satisfy the caller's permissions. Read & write can permit production operations when the caller has access, so it should not be treated as a staging-only setting.
Figure 2: The Guardrails tab with Read-only selected and the tool catalog visible.
A tool may still appear in the client's tool list when the selected level prevents its use. Akuity enforces the limit when the agent calls the tool.
Ask Your Fleet a Question
Discover Your Instances
Ask the agent to discover what you can access:
Figure 3: An instance discovery request through the platform connection. Your response will contain your own instance names and IDs.
Use the returned organization and instance names to scope the following requests. If an expected instance is unavailable, check that MCP access is enabled for it and that your account has permission to access it.
Find out which versions are running
Start with a question that spans your accessible environments:
Across the enabled Argo CD instances I can access, report the application-version distribution. Include each application's name,instance, container image tags and digests, health, and sync status.
Group by environment where the labels or configuration identify it,and mark the environment as unknown otherwise. Flag unhealthyapplications.
Specifying what you mean by “version” makes the answer more useful. A Git revision identifies desired configuration, while a container image tag or digest identifies the workload image. Ask the agent to distinguish the image declared in the desired configuration from the image reported by running workloads where that information is available.
The report gives you a starting point for spotting unexpected version differences or applications that need attention. Check a representative application against its Argo CD view, and ask the agent to identify any instances or data it could not inspect.
Figure 4: A real fleet query and response showing application names, instances, image versions, health, and sync status. Use the same applications throughout the walkthrough.
Investigate a Single Application
Choose an application from the report. In the requests below, replace APPLICATION and INSTANCE with its application name and Argo CD instance name or ID. You can review a healthy application's deployment history or investigate one that needs attention:
Investigate APPLICATION in Argo CD instance INSTANCE. What changed in its last deployment, and what do its resource state and events tell us?
Include related Kargo promotion and verification history if available.Summarize the evidence before suggesting a change.
The agent can connect application state with delivery history and inspect the resources involved. Available workload logs can add evidence, but they require the relevant data collection to be enabled for the organization, Argo CD instance, and cluster.
Use the response to separate observations from possible causes. A deployment preceding an error is a useful lead; resource events, logs, and verification results help determine whether the release explains the problem.
These inspection requests work within read-only MCP access.
Sync an Application Through the Guardrails
See a blocked request
Try this optional step when your team has a staging or development application ready for a manual sync. Choose it from the report and review its desired revision and pending diff using your normal deployment process. Your account must have permission to sync it, while the organization's MCP level remains Read-only.
Using Akuity MCP, sync APPLICATION in Argo CD instance INSTANCE to the desired revision we reviewed. If the request is denied, report the error.
When the agent calls the sync tool, Akuity rejects the request before execution. The tool error identifies both the level required for the operation and the organization's configured level. The blocked call does not sync the application.
Figure 5: An actual MCP sync rejection showing the required Read & write level and the configured Read-only level.
This demonstrates the distinction between the engineer's access and what the agent may do through MCP. The rejection is enforced by Akuity, independently of the wording in the prompt.
Allow the operation and verify it
If your organization is ready to permit write operations through MCP, an authorized administrator can select Read & write under Guardrails and save the setting. Remember that this changes the organization's MCP limit, not just this application's access.
Repeat the reviewed sync request for the same application and instance. With the required permissions and guardrail level, the request can proceed. Ask the agent to follow the sync to completion and report the application's health. Verify both before considering the work finished.
For a promotion through Kargo, the configured release requirements still apply. Permission to request a promotion does not remove those requirements.
An Organization Owner can review the recorded sync in Audit Logs, using Actor → Via MCP only. The entry identifies the authorizing caller and marks its MCP origin.
Figure 6: Use the Actor filter's Via MCP only option to find recorded MCP activity.
These audit entries cover recorded changes to managed state. Reads, application refreshes, and native-agent conversations do not create those mutation audit entries. See the Audit Logs documentation for the platform's audit views and archive downloads.
Hand the Investigation to Akuity’sOn-Call Agent
The plugin also includes akuity:delegate, which guides your client through working with Akuity's specialized agents. When you have an application that needs investigation and the relevant services are enabled, you can use Read & write access to ask:
Use the Akuity delegate skill to have the On-call Agent investigate APPLICATION in Argo CD instance INSTANCE and keep me updated.
In Claude Code, you can also invoke /akuity:delegate directly. Your client can start the native-agent conversation, follow its progress, and bring findings and proposed actions back to you. The same skill can ask the Promotion Advisor to assess a Kargo release.
Figure 7: A real delegation conversation showing the On-call Agent's findings and the external client's follow-up.
Review proposed actions before proceeding. Approving a native-agent tool action through MCP requires Full access and update permission on the target instance. The plugin guides that approval workflow; Akuity enforces the required permissions and MCP level. Client confirmation prompts are not a universal server-side approval requirement for other MCP mutations.
For application setup, the repository also includes akuity:onboard, which guides onboarding through the platform endpoint.
Try It with Your Environment
The Akuity MCP Server is available in Early Access for selected organizations on Akuity Cloud. Contact your Akuity account team or support to request access.
Start with one fleet question and read-only access. The Akuity agent-plugins repository provides installation instructions and workflow skills, and the connection reference covers endpoint and authentication options.
Additional Resources
Book a demo — Contact us today; we will map the Control Plane to your delivery setup.
Introducing the Akuity Agentic Control Plane and MCP Server — why we built it and how governance is implemented
Agentic Control Plane documentation: connecting a client, agent permissions, audit filtering
Akuity MCP Server reference: endpoints and the available tool catalog
Akuity agent-plugins repository: installation for Claude Code and Codex, plus the maintained skills
Connection and authentication reference: platform and direct instance endpoints
Full demo video — an agent troubleshooting, promoting, and onboarding through the Control Plane
Frequently Asked Questions
Q: Can an agent connected through the Akuity MCP Server do more than the person who connected it?
A: No. Every MCP request is authenticated as the specific user or API key that connected the agent, and the request must satisfy that caller's existing Akuity permissions. The organization's guardrail level can only narrow what an agent may do — it never grants access the connecting user does not already have.
Q: What do the three Akuity MCP guardrail levels allow?
A: Read-only, the default, permits inspection of applications, resources, events, available logs, and delivery history. Read & write adds operations such as sync, refresh, rollback, promotion, restart, and manifest application. Full also allows deletion, resource patching, instance-spec application, and approval of native-agent tool actions. Each level is cumulative and applies across the entire organization.
Q: Is Read & write a safe setting for teams that only want agents acting in staging?
A: No. The guardrail level applies to the whole Akuity organization, not to a single environment or application, so Read & write permits production operations wherever the connecting user already has permission to perform them. Environment scoping comes from the caller's own permissions, not from the guardrail level.
Q: Are actions taken by an agent recorded in the Akuity audit log?
A: Changes to managed state are recorded under the user or API key that authorized them and tagged as MCP actions, which an Organization Owner can isolate with the Actor → Via MCP only filter. Reads, application refreshes, and native-agent conversations do not create those mutation entries.
