Skip to main content

Connect MCP clients

For the platform endpoint, the recommended connection method is the Akuity agent plugin. It configures the MCP server and adds maintained workflow skills. Use the manual instructions when the plugin is unavailable for your client, when you need a different platform region, or when you prefer to configure MCP directly.

Direct instance endpoints must be connected manually. See Argo CD MCP Access and Kargo MCP Access.

Install the Akuity agent plugin​

Connecting the MCP server gives an agent access to individual tools. The optional Akuity agent plugin adds maintained workflow skills for tasks that require sequencing, platform knowledge, or a consistent approval flow.

The plugin is published in akuity/agent-plugins, which hosts Akuity workflow guidance and MCP configuration for supported agent clients. It includes two skills:

  • /akuity:onboard: Run onboarding end to end, whole or in part: provision Argo CD and Kargo instances, connect clusters, deploy an application across environments, and build a Kargo promotion pipeline. The user chooses how far to go. This skill requires the platform endpoint.
  • /akuity:delegate: Delegate work to AI Agents: start a conversation with the Deployment Advisor, hand a degraded Argo CD application to the On-Call Agent, or ask the Promotion Advisor to assess a Kargo promotion. The client follows the agent's work, relays proposed actions for human approval, and reports the result. This skill works with either the platform endpoint or a direct instance endpoint.

In Claude Code, invoke a skill directly with /akuity:onboard or /akuity:delegate, or describe the outcome you want and let Claude select the appropriate skill. In Codex, describe the desired outcome and let Codex select the appropriate bundled skill.

Install the marketplace and plugin:

/plugin marketplace add akuity/agent-plugins
/plugin install akuity@akuity

The default installation uses the US platform endpoint. When prompted for Platform MCP endpoint, EU organizations should select https://eu.akuity.cloud/mcp. To configure the EU endpoint non-interactively from a shell, run:

claude plugin install akuity@akuity --config endpoint=https://eu.akuity.cloud/mcp

The plugin configures the platform endpoint. It does not configure a direct instance endpoint. The plugin is optional, and users can connect to either MCP endpoint without installing it.

Connect Claude.ai, Claude Desktop, and Cowork​

Claude.ai, Claude Desktop, and Cowork support custom connectors on Free, Pro, Max, Team, and Enterprise plans. Free users are limited to one custom connector. Use your Akuity platform endpoint:

  • US: https://akuity.cloud/mcp
  • EU: https://eu.akuity.cloud/mcp
  • Self-hosted: https://<PORTAL_HOSTNAME>/mcp; complete the self-hosted setup first.

On Team plans, an Owner or Primary Owner adds the connector for the organization. Enterprise plans also allow a custom role with Manage access to Libraries permission:

  1. Open Organization settings → Connectors.
  2. Click Add, hover over Custom, and select Web.
  3. Enter a connector name and your Akuity platform endpoint URL, then click Continue.
  4. Review the detected authentication settings, then click Continue.
  5. Apply the browser sign-in settings below, then click Add.

Each member then connects with their own identity:

  1. Open Customize → Connectors.
  2. Find the Akuity custom connector and click Connect.
  3. Sign in with your Akuity account and approve the one-time Akuity consent page that names the Claude callback.

Browser sign-in settings​

These settings use each person's Akuity identity:

  1. Under Authentication, select Sign in now.
  2. Under OAuth client, select Use Claude's published identity.
  3. Leave the Advanced settings unchanged and add no request headers. You do not need to enter an OAuth client ID or client secret in Claude.
Add custom connector with Sign in now and Use Claude's published identity selected

For the latest plan-specific navigation and connector behavior, see Anthropic's custom connector instructions.

Connect manually​

Any client that supports Streamable HTTP and OAuth can connect. Prefer the snippets generated by the portal under Organization Settings → MCP Access; they use the server name akuity and the endpoint for your region. The exact configuration file and OAuth behavior depend on the client. Clients that use a custom-scheme or hosted callback (for example Cursor or Claude.ai) work with the platform endpoint after a one-time consent screen.

EU organizations replace https://akuity.cloud/mcp with https://eu.akuity.cloud/mcp in the snippets below. Self-hosted installations use https://<PORTAL_HOSTNAME>/mcp; see Self-hosted Agentic Control Plane.

claude mcp add --transport http akuity https://akuity.cloud/mcp

The client opens a browser to sign in on the first connect. Use /mcp to inspect connection and authentication status.

Use an Akuity API key​

Use an API key with the platform endpoint for automation or when the client cannot complete the OAuth flow. Use the endpoint of the region that hosts the organization the key belongs to. Send the key ID and secret as one bearer value separated by a colon:

Authorization: Bearer <API_KEY_ID>:<API_KEY_SECRET>
caution

Store the key in a secret manager or environment variable. Do not paste it into prompts, commit it to a repository, or include it in screenshots.

Claude Code API-key example​

Set AKUITY_API_KEY_ID and AKUITY_API_KEY_SECRET in the environment that starts Claude Code, using your secret manager. Add this entry to your project's .mcp.json, merging it with any existing servers. For EU or self-hosted installations, replace the URL with your platform endpoint.

{
  "mcpServers": {
    "akuity": {
      "type": "http",
      "url": "https://akuity.cloud/mcp",
      "headers": {
        "Authorization": "Bearer ${AKUITY_API_KEY_ID}:${AKUITY_API_KEY_SECRET}"
      }
    }
  }
}

Keep the ${...} references as written. Claude Code expands them from the environment when it connects. If you already configured akuity in the project's local scope, update that entry or remove it with claude mcp remove akuity --scope local so it does not override this file. Start a new session, approve the project server when prompted, and use /mcp to check the connection. API-key authentication does not require browser sign-in.

Verify the connection​

Confirm that the client reports the akuity MCP server as connected and that your chosen authentication method succeeded. First, check access to the platform's instance list:

List my Argo CD and Kargo instances on Akuity Platform.

Verify the platform endpoint

Then read data from an instance with MCP access enabled. Replace the names below with your own and use the prompt for the product you run:

List applications in Argo CD instance <ARGO_CD_INSTANCE_NAME>.
List projects in Kargo instance <KARGO_INSTANCE_NAME>.

Confirm that the result matches the instance's UI. An empty list is valid when the instance has no applications or projects. Listing instances alone does not check whether the platform can reach an instance's API. For self-hosted installations with multiple regions, repeat the read for an enabled instance in each region. Reconnect the client and repeat one read to check that the saved credentials still work.

If the agent cannot see an instance or a tool is missing, see Troubleshooting.