Set up and configure the Astro Private Cloud MCP server

This page is for System Admins. Enable the Astro Private Cloud (APC) Model Context Protocol (MCP) server, choose which tools it exposes, enable skills, and turn it off. End users connect a client from the MCP server overview. For what an agent can reach and as whom, see the MCP server security posture.

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.

Every MCP server setting is a Helm chart value under the astronomer key. There is no UI and no runtime configuration, so every change (enabling the server, adding a tool group, or disabling a single tool) is a helm upgrade. Because there is no fast in-product toggle, plan your incident path around the chart. See Disable the server.

Prerequisites

The MCP server runs on the control plane or a unified plane only. It isn’t deployed on a data plane, regardless of the enable flag.
The platform’s own NGINX must serve the ingress. Bring-your-own-ingress (global.authSidecar.enabled) is unsupported: enabling the MCP server with the auth sidecar set triggers a Helm fail and the install or upgrade stops. This also rules out an Istio Gateway, which requires the auth sidecar. See Authentication.
Apply every change with a helm upgrade. See Apply a platform configuration change.

Enable the server

The server is off by default. Enable it with a single value.

Set the enable flag

astronomer:
  mcpServer:
    enabled: true

Apply the change

helm upgrade <your-installation-release-name> astronomer/astronomer -f <your-updated-config-yaml-file> -n <your-installation-namespace> --set astronomer.houston.upgradeDeployments.enabled=false

Setting astronomer.houston.upgradeDeployments.enabled=false keeps this MCP-only change from restarting the Airflow components in unrelated Deployments.

With no further configuration, the server comes up with the two default tool groups (platform_read and platform_write) enabled. The server is stateless and runs two replicas by default (astronomer.mcpServer.replicas).

Choose tool groups

You enable tools by group, not one by one. astronomer.mcpServer.enabledGroups lists the groups the server exposes.

Group	Surface	Default	Contents
`core`	—	Always on	Health and liveness checks. Exposes no tools to callers. Not configurable, and you don’t need to list it.
`platform_read`	Platform	On	Read-only platform operations: list and get Deployments, Workspaces, revisions, runtime versions, namespaces.
`platform_write`	Platform	On	Platform writes: create and update Deployments and Workspaces, deploy images, manage Workspace users and teams, roll back a Deployment.
`platform_disruptive`	Platform	Off	Deployment contract changes: migrate executor, runtime version, or Dag (directed acyclic graph) delivery mode.
`platform_destroy`	Platform	Off	Destructive platform operations: delete a Deployment or a Workspace.
`airflow_read`	Airflow	Off	Airflow diagnosis: task logs, import errors, installed providers, Airflow and component health, upgrade-safety checks, Dag stats, Dag run detail and diagnosis.
`airflow_destroy`	Airflow	Off	Destructive Airflow operations: delete and clear Dag runs, clear task instances.
`skills_load`	—	Off	Skill delivery. Controlled by `astronomer.mcpServer.skills.enabled`, not by this list. See Enable skills.

astronomer.mcpServer.enabledGroups is a replacement list, not an addition to the defaults. If you set it, you set the whole list. Any group you omit is disabled, including platform_read and platform_write. To add Airflow reads on top of the defaults, list all three:

astronomer:
  mcpServer:
    enabledGroups:
      - platform_read
      - platform_write
      - airflow_read

Agent-driven contract changes (platform_disruptive) and agent-driven deletion (platform_destroy, airflow_destroy) are deliberately separate from the everyday read and write groups. Turn them on only when you intend agents to take those actions. The server doesn’t prompt the user before a destructive call. It requires confirm: true on the seven tools that take a confirm argument, but showing a prompt to the user is up to the client. See Stated limitations.

Tool surfaces

You can enable the platform and Airflow surfaces independently.

The APC API’s GraphQL serves platform operations (the platform_* groups). They depend only on the APC API and work on every deployment model.
The airflow_* groups serve Airflow state. Its Laminar-served tools also require the Laminar component, which is off by default and enabled platform-wide:

global:
  laminar:
    enabled: true

Within the Airflow surface, task logs, import errors, installed providers, and health checks reach the Deployment’s Airflow REST API through the APC API and work on both Helm-based and operator Deployments, as do clearing task instances and clearing or deleting Dag runs. Only the Dag run state tools (get_dag_stats, get_dag_run, get_dag_run_diagnosis) use the Laminar Airflow-state service and return results only for operator-based Deployments. Because the surfaces are independent, a Helm-based Deployment can run the platform tools without waiting on the operator migration.

Enable skills

Skills are off by default and toggle separately from the tool groups.

astronomer:
  mcpServer:
    skills:
      enabled: true

Enabling skills exposes the skill-delivery tools and the two bundled skills, debugging-dags and migrating-airflow-2-to-3. It also implies the read-only groups those skills need (platform_read and airflow_read), so you don’t have to add them to enabledGroups by hand. Skills imply only read-only groups, so a skill never widens the destructive surface. When skills.enabled is true, the chart adds the skills_load group to the rendered enabledGroups list. Don’t list skills_load yourself.

Disable a single tool

astronomer.mcpServer.disabledTools hides named tools from the catalog and refuses any call to them. It outranks everything, including a group a tool belongs to and core.

astronomer:
  mcpServer:
    disabledTools:
      - delete_workspace

Use it to remove one tool from an otherwise-enabled group. For example, enable platform_destroy but list delete_workspace here to keep that one tool off while the rest of the group stays on.

What a caller sees without the Airflow tools

The catalog reflects the enabled groups. When airflow_read and airflow_destroy are both off, the Airflow-state tools are absent from the catalog, so the agent can’t offer or call them. When the Airflow tools are enabled but the target is a Helm-based Deployment, the Laminar-backed Dag run tools (get_dag_stats, get_dag_run, get_dag_run_diagnosis) appear in the catalog but return an unsupported error for that Deployment, while task logs and the other Airflow REST tools still work.

Tune the Laminar passthrough

The Laminar Airflow-state service is reached through an APC API passthrough with two settings. They tune the APC API route whenever a caller is authorized to reach it, whether or not the MCP server is enabled.

Value	Default	Description
`astronomer.laminar.maxConcurrentPerDeployment`	`10`	Maximum concurrent in-flight passthrough requests per Deployment. Beyond it, requests are shed with a `429` response that clients can retry, protecting other Deployments and non-agent callers.
`astronomer.laminar.timeoutMs`	`30000`	Per-request upstream timeout, in milliseconds.

The concurrency cap is enforced per APC API replica, in memory, not as a cluster-wide ceiling. With N replicas the effective cap is N times the configured value. Size it per replica, not as a global limit.Keep astronomer.laminar.timeoutMs below 35000. The MCP server’s own Laminar client gives up at 35 seconds, so a larger upstream timeout means the client abandons the request before the real response arrives.

Full values reference

A complete MCP server configuration, with defaults:

global:
  # Enables the Laminar component that the Airflow-state tools depend on.
  laminar:
    enabled: false
  networkPolicy:
    enabled: true

astronomer:
  mcpServer:
    enabled: false
    replicas: 2

    # Replacement list of tool groups. Omitted groups are disabled.
    enabledGroups:
      - platform_read
      - platform_write

    # Skills toggle. Implies the read-only groups the shipped skills need.
    skills:
      enabled: false

    # Per-tool kill switch. Outranks everything, including core.
    disabledTools: []

    # nginx auth_request caching. A latency and load knob, not a security
    # control: every tool call is re-authorized against the APC API regardless.
    authCache:
      enabled: true
      validSuccess: "5m"
      validFailure: "1m"

    resources:
      requests:
        cpu: "100m"
        memory: "128Mi"
      limits:
        cpu: "500m"
        memory: "512Mi"

  images:
    mcpServer:
      repository: quay.io/astronomer/ap-apc-mcp-server
      tag: "1.0.6"

  ports:
    mcpServerHTTP: 8080
    mcpServerMetrics: 9090

  # APC API passthrough to Laminar. Applies whenever a caller is authorized to
  # reach the route, independent of mcpServer.enabled.
  laminar:
    maxConcurrentPerDeployment: 10
    timeoutMs: 30000

The platform NetworkPolicy, rendered when global.networkPolicy.enabled is set (the default), admits only the control plane ingress controller and the metrics scraper to the server, so no other in-cluster workload can bypass the authentication gate. See Authorization.

Disable the server

Turn the server off with the same flag and a helm upgrade.

astronomer:
  mcpServer:
    enabled: false

helm upgrade <your-installation-release-name> astronomer/astronomer -f <your-updated-config-yaml-file> -n <your-installation-namespace> --set astronomer.houston.upgradeDeployments.enabled=false

With no runtime toggle, this helm upgrade is the supported way to disable the server. For faster emergency options, see Disable the server. astronomer.houston.upgradeDeployments.enabled=false keeps the upgrade from restarting the Airflow components in unrelated Deployments.

​Prerequisites

​Enable the server

​Choose tool groups

​Tool surfaces

​Enable skills

​Disable a single tool

​What a caller sees without the Airflow tools

​Tune the Laminar passthrough

​Full values reference

​Disable the server

Prerequisites

Enable the server

Choose tool groups

Tool surfaces

Enable skills

Disable a single tool

What a caller sees without the Airflow tools

Tune the Laminar passthrough

Full values reference

Disable the server