Skip to main content
Use Symptom to cause and the error reference to debug a tool call. Use Disable the server to handle an incident. The sections don’t depend on each other.
Astro Private Cloud 2.2This feature was introduced in Astro Private Cloud 2.2. To access this feature, upgrade your Astro Private Cloud installation to 2.2 or later.

​
Symptom to cause

​
The gate rejects every request

The MCP server has no authentication code of its own. Every request passes through the platform’s NGINX ingress first, which makes an auth_request subrequest to the APC API’s /v1/authorization/agent endpoint before the request reaches the MCP server. A rejection at this gate is a plain HTTP 401 at the ingress layer, not a tool-call error, because the request never reached the server’s code. Check, in order:
  1. Is the credential valid? The gate accepts APC API JSON Web Tokens (JWTs), service-account keys, and identity provider (IdP) tokens, and clients typically use a service-account API key as a static bearer token. Confirm the token hasn’t expired, been rotated, or been deleted. See Authentication.
  2. Is a stale cache result being served? The gate caches each verdict by bearer token: a success for astronomer.mcpServer.authCache.validSuccess (five minutes by default) and a denial for astronomer.mcpServer.authCache.validFailure (one minute by default). A revoked or expired key can keep passing until its cached success expires. A key you just fixed can take up to a minute to start working again.
  3. Is bring-your-own-ingress or an Istio Gateway enabled? Both set global.authSidecar.enabled, which together with astronomer.mcpServer.enabled fails the whole Helm install or upgrade, rather than coming up with an unauthenticated gate. If the server won’t deploy, check Availability before assuming a token problem.

​
Laminar unreachable, Laminar returned an error, or the Deployment isn’t operator-based

These three causes aren’t equally distinguishable. A Deployment that isn’t operator-based reports as unsupported, since the Airflow-state tools (get_dag_stats, get_dag_run, get_dag_run_diagnosis) only work on operator-based Deployments. Check the Deployment’s mode before assuming anything else is wrong. An unreachable Laminar and a Laminar error both report as upstream, so the kind can’t tell them apart. The message text that follows the kind names the specific upstream failure. Read the message, not just the kind, when triaging an upstream error from these tools.

​
Task logs come back empty

The MCP server doesn’t distinguish “this task’s logs haven’t shipped yet” from “this task’s logs are gone.” Both return a successful response with empty log content, and there’s no special error for the in-flight case. The only signal is the task instance’s state, included in the response when the log attempt you asked for matches the task’s current attempt number. A running state alongside empty content usually means the logs haven’t flushed yet, so wait and ask again. A terminal state (success or failed) alongside empty content more likely means the logs are actually gone (for example, an evicted worker, or a retention window that has passed). If you asked for an earlier attempt than the task’s current one, the response omits state entirely, so the signal isn’t available for a stale tryNumber.

​
A tool is missing from tools/list

Three causes are possible. The pod’s health tells you which:
  • Its tool group isn’t enabled. Check astronomer.mcpServer.enabledGroups in the chart values against the tool’s group. This is a normal, healthy state. The pod runs fine either way.
  • It’s named in astronomer.mcpServer.disabledTools. This outranks everything, including an otherwise-enabled group. Also a normal, healthy state. A misspelled name in this list logs a boot-time warning and disables nothing, so check here if a tool you meant to disable is still visible.
  • A genuine registration failure. The pod never becomes ready (CrashLoopBackOff), rather than running with one tool missing. If the pod is Running and ready, the cause is one of the first two. Otherwise, collect the pod logs and contact Astronomer support.

​
Error reference

Every tool error is one line, <kind>: <message>. The kind is a stable, machine-readable discriminator. The message is free text to read, not pattern-match.

​
Disable the server

Options are listed fastest first. There’s no in-product toggle, and only the last option is a helm upgrade.
  1. Revoke the credential at the gate. Revoke or rotate the service-account key through the APC API. Tools that call the APC API fail on the next call, but the gate can keep letting the key through until its cached success expires (five minutes by default). The pod keeps running, and nothing is redeployed.
  2. Scale to zero. Immediate, and doesn’t touch Helm:
    This assumes the chart was installed under its default release name. If you set astronomer.mcpServer.fullnameOverride or used a non-default release name, find the actual Deployment name first:
    Scaling to zero doesn’t change the Helm value, so the APC UI keeps showing the MCP server as enabled, and any client that tries to connect gets errors, until you run a helm upgrade. Use this option to stop traffic during an incident, then follow with option 3.
  3. Turn off the chart flag, or pin a previous image. Set astronomer.mcpServer.enabled: false, or pin astronomer.images.mcpServer.tag back to a known-good version, and apply it with a helm upgrade. Slower than the previous two options because it’s a full upgrade, but it’s the only one that removes the component rather than pausing it.
None of these options undo what the server already did. A mutating tool call that committed through the APC API stays committed, and disabling or rolling back the MCP server doesn’t roll back its effects. Recover from an unwanted mutation through the APC API’s own mechanisms (for example, rollback_deployment).