> ## Documentation Index
> Fetch the complete documentation index at: https://astronomer.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Set up and configure the Astro Private Cloud MCP server

> Enable, configure, and disable the Astro Private Cloud MCP server through Helm chart values.

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](https://astronomer.io/docs/astro-private-cloud/v-2-x/apc-mcp-server.md). For what an agent can reach and as whom, see the [MCP server security posture](https://astronomer.io/docs/astro-private-cloud/v-2-x/apc-mcp-server-security.md).

> [!NOTE]
>
> **Astro Private Cloud 2.2**
>
> This feature was introduced in Astro Private Cloud 2.2. To access this feature, upgrade your Astro Private Cloud installation to 2.2 or later.

> [!NOTE]
>
> 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](#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](https://astronomer.io/docs/astro-private-cloud/v-2-x/istio-gateway.md), which requires the auth sidecar. See [Authentication](https://astronomer.io/docs/astro-private-cloud/v-2-x/apc-mcp-server-security.md#authentication).
* Apply every change with a `helm upgrade`. See [Apply a platform configuration change](https://astronomer.io/docs/astro-private-cloud/v-2-x/apply-platform-config.md).

## Enable the server

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

**1. Set the enable flag**

```yaml wrap theme={null}
astronomer:
  mcpServer:
    enabled: true
```

**2. Apply the change**

```bash wrap theme={null}
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](#enable-skills). |

> [!WARNING]
>
> `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:
>
> ```yaml wrap theme={null}
> 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](https://astronomer.io/docs/astro-private-cloud/v-2-x/apc-mcp-server-security.md#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:

```yaml wrap theme={null}
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.

```yaml wrap theme={null}
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`.

```yaml wrap theme={null}
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. |

> [!WARNING]
>
> 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:

```yaml wrap theme={null}
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](https://astronomer.io/docs/astro-private-cloud/v-2-x/apc-mcp-server-security.md#authorization).

## Disable the server

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

```yaml wrap theme={null}
astronomer:
  mcpServer:
    enabled: false
```

```bash wrap theme={null}
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](https://astronomer.io/docs/astro-private-cloud/v-2-x/apc-mcp-server-runbook.md#disable-the-server). `astronomer.houston.upgradeDeployments.enabled=false` keeps the upgrade from restarting the Airflow components in unrelated Deployments.