Skip to main content

Troubleshooting

The client cannot find the endpoint​

  • Confirm that Akuity has enabled Early Access for the organization.
  • Confirm that the relevant platform or instance toggle is enabled and the change has been saved.
  • For a newly enabled instance, wait for reconciliation to complete. A direct endpoint may return 404 until the /mcp route is published.
  • Confirm that the URL ends in /mcp and uses HTTPS.
  • Argo CD instances configured with a basepath cannot serve the direct endpoint yet. Use the platform endpoint to reach them.
  • Confirm the region: EU organizations use https://eu.akuity.cloud/mcp, not https://akuity.cloud/mcp. A client pointed at the other region cannot find your organization.

Browser sign-in does not complete​

  • Platform endpoint: Confirm that the user can sign in to Akuity Cloud, including the organization's SSO flow. If the browser shows an Akuity consent page, review the redirect destination it names and approve it; this appears for hosted and custom-scheme clients. Reconnect the client after changing authentication or endpoint settings.
  • Direct instance endpoint with Dex: Confirm that the client uses a loopback callback on the localhost hostname, not 127.0.0.1 or ::1, and that the client is not hosted.
  • Direct instance endpoint with OIDC: Confirm that https://<ARGO_CD_HOSTNAME>/mcp/oauth/callback for Argo CD or https://<KARGO_HOSTNAME>/mcp/oauth/callback for Kargo is registered on the public OAuth client shown in the instance's MCP Access settings. The issuer must use HTTPS. A redirect-mismatch error from the identity provider means the callback is missing.
  • Direct instance endpoint using username/password login: Confirm that the client uses a loopback callback and that the account's password is correct; the instance itself checks it.
  • If browser sign-in is unavailable, use an appropriate Akuity API key for the platform endpoint or a native instance token for a direct endpoint.

The agent cannot see an instance​

  • Confirm that the instance is enabled under Organization Settings → MCP Access → Instance access.
  • Confirm that the authenticated identity has get or update permission on the instance.
  • After permissions or MCP access change, allow up to 30 seconds for the server's visibility cache to refresh, then reconnect the client.
  • Run list_organizations and confirm that the intended organization name and ID appear. If it is missing, verify the connected region and signed-in account. Use the returned ID for organization-level tools.

A tool is missing or denied​

  • Confirm that the client is connected to the correct endpoint. Some tools are available only from the platform endpoint or only from a direct instance endpoint. See the tool reference.
  • Confirm that the authenticated user has the required get or update permission in Akuity, Argo CD, or Kargo.
  • Confirm that the organization's guardrail level allows the tool. A call above the level fails with an error naming both levels.
  • After permissions or MCP access change, allow up to 30 seconds for the server's visibility cache to refresh, then reconnect the client.

A tool call is rejected with a guardrail error​

The organization's guardrail level is below the level the tool requires. Raise it under Organization Settings → MCP Access → Guardrails and click Save. See Set the guardrail level.

The Add custom connector option is missing in Claude.ai​

  • On Team and Enterprise plans, only an Owner or Primary Owner can add a custom connector for the organization. Members connect to it afterward under Customize → Connectors.
  • On Free, Pro, and Max plans, open Customize → Connectors, click +, and select Add custom connector. Free users are limited to one custom connector.
  • If the option is still unavailable, check Anthropic's current custom connector instructions.

get_k8s_workload_logs reports "no Kubernetes resource with UID ..."​

The workload lookup uses data collected by Akuity Agents. Enable Akuity Agents for the organization, on the Argo CD instance, and on the target cluster, then allow a few minutes for the agent to sync.

Early Access limitations​

The Early Access release is intended to validate endpoint compatibility, permissions, and real-world agent workflows before general availability. The following constraints may change as the feature evolves:

  • Direct endpoints on Dex-backed instances accept loopback callbacks on the localhost hostname only and do not support hosted clients.
  • Direct endpoints are not available on Argo CD instances configured with a basepath.
  • Username/password sign-in does not issue a refresh token. The client signs in again when the instance session expires (24 hours by default).
  • Tool names, input schemas, and availability may change before general availability.