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 Akuity 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 the Akuity platform endpoint for your organization's region:

  • US: https://akuity.cloud/mcp
  • EU: https://eu.akuity.cloud/mcp

An Owner or Primary Owner adds the connector for the organization:

  1. Open Organization settings → Connectors.
  2. Click Add, hover over Custom, and select Web.
  3. Enter the Akuity platform endpoint URL for the organization's region.
  4. Leave Advanced settings empty. Do not provide an OAuth client ID, client secret, or request headers.
  5. 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.
Add custom connector Add custom connector, advanced settings

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.

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.

Verify the connection​

Confirm that the client reports the akuity MCP server as connected and that browser authentication completed successfully. Then use a prompt like the following:

List my Argo CD and Kargo instances on Akuity Platform.

Verify the platform endpoint

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