> ## 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.

# Astro Private Cloud MCP server tool reference

> Every tool the Astro Private Cloud MCP server exposes: its arguments, its MCP permission label, its effect, and whether it restarts a Deployment.

The Astro Private Cloud (APC) Model Context Protocol (MCP) server exposes 37 tools, grouped into seven tool groups. A tool group is a Helm chart toggle: disabling a group removes its tools from the catalog entirely, not just from what a given caller can see. See [Set up and configure the MCP server](https://astronomer.io/docs/astro-private-cloud/v-2-x/apc-mcp-server-setup.md#choose-tool-groups) to enable or disable a group and for which groups are on by default. The always-on `core` group handles health and liveness checks and exposes no tools to callers, so it isn't listed here.

> [!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.

Each tool declares an *effect* (Read, Mutate, or Destroy) that a client can use to decide whether a call needs confirmation. Effect and group are independent: a few tools in the `platform_write` group (for example `rollback_deployment`) have a Destroy effect even though the group isn't `platform_destroy`. Check a tool's own effect rather than assuming it from its group.

The MCP permission listed for each tool is the server's own label, not an APC API permission, and doesn't appear in APC roles. The APC API authorizes every call against the caller's own role, so a call succeeds only when that role allows the underlying action.

The server doesn't prompt the user before a call. Destructive tools carry a `destructiveHint` annotation that a client can use to ask the user first, but the hint is advisory, and the agent decides whether to honor it. The server also requires `confirm: true` on the seven tools that take a `confirm` argument and rejects any call without it with a `denied` error, whatever the client does.

## Platform read (`platform_read`, on by default)

Read-only platform operations. They report state and don't restart Deployments.

| Tool | Effect | MCP permission |
| - | - | - |
| `deployment_status` | Read | `deployment.get` |
| `list_workspaces` | Read | `workspace.list` |
| `list_runtime_versions` | Read | `runtime_version.list` |
| `list_namespaces` | Read | `namespace.list` |
| `list_deployments` | Read | `deployment.list` |
| `get_deployment` | Read | `deployment.get` |
| `list_deploy_revisions` | Read | `deployment.list_revisions` |

> [accordion] deployment\_status
>
> | Argument | Type | Required | Description |
> | - | - | - | - |
> | `deployment` | string | Yes | The Deployment identifier to report on. |

> [accordion] list\_workspaces
>
> No arguments.

> [accordion] list\_runtime\_versions
>
> No arguments.

> [accordion] list\_namespaces
>
> | Argument | Type | Required | Description |
> | - | - | - | - |
> | `cluster` | string | No | Cluster identifier to scope the scan. Omit to scan cluster-wide. |

> [accordion] list\_deployments
>
> | Argument | Type | Required | Description |
> | - | - | - | - |
> | `workspace` | string | Yes | The Workspace identifier to list Deployments in. |
> | `name` | string | No | Filter matching label, release name, description, or runtime version. |

> [accordion] get\_deployment
>
> | Argument | Type | Required | Description |
> | - | - | - | - |
> | `deployment` | string | Yes | The Deployment identifier to report on. |
>
> Returns the Deployment's base info, active URLs, config summary, and environment variables.

> [accordion] list\_deploy\_revisions
>
> | Argument | Type | Required | Description |
> | - | - | - | - |
> | `deployment` | string | Yes | The Deployment identifier whose deploy history to list. |
>
> Use this to choose a revision for `rollback_deployment`.

## Platform write (`platform_write`, on by default)

Deployment and Workspace writes. `update_deployment`, `create_deployment`, `deploy_image`, and `rollback_deployment` restart the Deployment's Airflow components. Each call drives a Helm upgrade. Workspace membership and team tools don't touch a Deployment.

| Tool | Effect | Restarts a Deployment | MCP permission |
| - | - | - | - |
| `update_deployment` | Mutate | Yes | `deployment.update` |
| `create_deployment` | Mutate | Initial provisioning (nothing to restart yet) | `deployment.create` |
| `rollback_deployment` | Destroy | Yes | `deployment.rollback` |
| `deploy_image` | Mutate | Yes | `deployment.deploy_image` |
| `create_workspace` | Mutate | No | `workspace.create` |
| `update_workspace` | Mutate | No | `workspace.update` |
| `add_workspace_user` | Mutate | No | `workspace.add_user` |
| `remove_workspace_user` | Destroy | No | `workspace.remove_user` |
| `update_workspace_user_role` | Mutate | No | `workspace.update_user_role` |
| `add_workspace_team` | Mutate | No | `workspace.add_team` |
| `remove_workspace_team` | Destroy | No | `workspace.remove_team` |
| `update_workspace_team_role` | Mutate | No | `workspace.update_team_role` |

> [accordion] update\_deployment
>
> | Argument | Type | Required | Description |
> | - | - | - | - |
> | `deployment` | string | Yes | The Deployment to update. |
> | `label` | string | No | New label. |
> | `description` | string | No | New description. |
> | `properties` | object | No | Free-form Deployment properties. |
> | `environmentVariables` | array | No | Each entry: `{key, value, isSecret}`. Pass `value: null` (not omitted) to delete a key. |
> | `workers`, `scheduler`, `webserver`, `apiServer`, `triggerer`, `dagProcessor`, `pgbouncer`, `statsd`, `redis`, `flower` | object | No | Per-component configuration. |
>
> Every argument besides `deployment` is optional. Always pass `isSecret` for an environment variable. Leaving it out stores the value as a plain variable, even if it was a secret before. A component object such as `workers` or `scheduler` replaces that component's whole configuration, so pass every field, not just the one you're changing. Each call triggers a Helm restart of the Deployment.

> [accordion] create\_deployment
>
> | Argument | Type | Required | Description |
> | - | - | - | - |
> | `workspaceId` | string | Yes | Workspace to create the Deployment in. |
> | `clusterId` | string | Yes | Cluster to create the Deployment on. |
> | `label` | string | Yes | Deployment label. |
> | `executor` | string | Yes | Executor type. |
> | `runtimeVersion` | string | Yes | Astro Runtime version. |
> | `description`, `image`, `mode` (`helm` or `operator`), `releaseName`, `namespace` | string | No | — |
> | `environmentVariables` | array | No | Same shape as `update_deployment`. |
> | `properties`, `dagDeployment`, `workers`, `scheduler`, `webserver`, `apiServer`, `triggerer`, `dagProcessor`, `pgbouncer`, `statsd`, `redis`, `flower` | object | No | Per-component configuration. |
> | `metadataConnection`, `resultBackendConnection`, `inactiveMetadataConnection`, `inactiveResultBackendConnection` | string | No | Manual connection strings, each with a `*Json` object variant. |
> | `kerberosEnabled`, `skipAirflowDatabaseProvisioning` | boolean | No | — |
>
> This uses the same Helm-apply path as `update_deployment`, run for the first time for this Deployment, so there's nothing running yet to restart.

> [accordion] rollback\_deployment
>
> | Argument | Type | Required | Description |
> | - | - | - | - |
> | `deployment` | string | Yes | The Deployment to roll back. |
> | `deployId` | string | Yes | The deploy revision identifier to roll back to. Find one with `list_deploy_revisions`. |
> | `description` | string | Yes | Reason the rollback was initiated. |
> | `rollbackImage` | boolean | No | — |
> | `rollbackDags` | boolean | No | — |
> | `confirm` | boolean | Yes | Must be explicitly `true`. |
>
> Re-renders the Deployment to a prior Helm release. This restarts the Deployment, and you can reverse it only by rolling forward again.

> [accordion] deploy\_image
>
> | Argument | Type | Required | Description |
> | - | - | - | - |
> | `deployment` | string | Yes | The Deployment to deploy to. |
> | `image` | string | Yes | The Airflow image reference to deploy. |
> | `runtimeVersion` | string | Yes | The Astro Runtime version this image corresponds to. Changing it upgrades the Deployment's Airflow version, without the `confirm` that `migrate_deployment` requires. |

> [accordion] create\_workspace
>
> | Argument | Type | Required | Description |
> | - | - | - | - |
> | `label` | string | Yes | Workspace label. |
> | `description` | string | No | — |

> [accordion] update\_workspace
>
> | Argument | Type | Required | Description |
> | - | - | - | - |
> | `workspace` | string | Yes | The Workspace to update. |
> | `label`, `description` | string | No | — |

> [accordion] add\_workspace\_user
>
> | Argument | Type | Required | Description |
> | - | - | - | - |
> | `workspace` | string | Yes | — |
> | `email` | string | Yes | — |
> | `role` | string | Yes | For example `WORKSPACE_VIEWER`, `WORKSPACE_EDITOR`, `WORKSPACE_ADMIN`. |
> | `bypassInvite` | boolean | No | Skip the email invite flow. Defaults to `false`. |

> [accordion] remove\_workspace\_user
>
> | Argument | Type | Required | Description |
> | - | - | - | - |
> | `workspace` | string | Yes | — |
> | `user` | string | Yes | The user's identifier, not their email. |

> [accordion] update\_workspace\_user\_role
>
> | Argument | Type | Required | Description |
> | - | - | - | - |
> | `workspace` | string | Yes | — |
> | `email` | string | Yes | The user must already be a Workspace member. |
> | `role` | string | Yes | — |

> [accordion] add\_workspace\_team
>
> | Argument | Type | Required | Description |
> | - | - | - | - |
> | `workspace`, `team`, `role` | string | Yes | — |

> [accordion] remove\_workspace\_team
>
> | Argument | Type | Required | Description |
> | - | - | - | - |
> | `workspace`, `team` | string | Yes | — |

> [accordion] update\_workspace\_team\_role
>
> | Argument | Type | Required | Description |
> | - | - | - | - |
> | `workspace` | string | Yes | — |
> | `team` | string | Yes | The team must already have access to the Workspace. |
> | `role` | string | Yes | — |

## Platform disruptive (`platform_disruptive`, off by default)

Deployment contract changes: executor, runtime version, or Dag (directed acyclic graph) delivery mode. Kept separate from the everyday write group so enabling routine config updates never also enables contract changes.

| Tool | Effect | Restarts a Deployment | MCP permission |
| - | - | - | - |
| `migrate_deployment` | Mutate | Yes | `deployment.migrate` |

> [accordion] migrate\_deployment
>
> | Argument | Type | Required | Description |
> | - | - | - | - |
> | `deployment` | string | Yes | The Deployment to migrate. |
> | `executor` | string | No | For example `CeleryExecutor` or `KubernetesExecutor`. |
> | `runtimeVersion` | string | No | — |
> | `dagDeployment` | object | No | — |
> | `confirm` | boolean | Yes | Must be explicitly `true`. |
>
> A contract change, not a routine config update. Each call triggers a Helm restart, as `update_deployment` does.

## Platform destroy (`platform_destroy`, off by default)

Deletes a Deployment or a Workspace outright. Neither tool restarts anything, and both tear down a Helm release rather than re-rendering one.

| Tool | Effect | MCP permission |
| - | - | - |
| `delete_deployment` | Destroy | `deployment.delete` |
| `delete_workspace` | Destroy | `workspace.delete` |

> [accordion] delete\_deployment
>
> | Argument | Type | Required | Description |
> | - | - | - | - |
> | `deployment` | string | Yes | — |
> | `confirm` | boolean | Yes | Must be explicitly `true`. |

> [accordion] delete\_workspace
>
> | Argument | Type | Required | Description |
> | - | - | - | - |
> | `workspace` | string | Yes | — |
> | `confirm` | boolean | Yes | Must be explicitly `true`. |

## Airflow read (`airflow_read`, off by default)

Airflow diagnosis: task logs, import errors, installed providers, health, and Dag run detail. `get_task_logs`, `get_import_errors`, `get_installed_providers`, `get_airflow_health`, and `get_airflow_component_health` work on both Helm-based and operator-based Deployments. `get_dag_stats`, `get_dag_run`, and `get_dag_run_diagnosis` use the Laminar Airflow-state service and return results only for operator-based Deployments. `check_upgrade_safety` reaches neither the APC API nor a live Deployment. It screens a version against a vendored knowledge base.

| Tool | Effect | MCP permission |
| - | - | - |
| `get_task_logs` | Read | `deployment.airflow.logs` |
| `get_import_errors` | Read | `deployment.airflow.import_errors` |
| `get_installed_providers` | Read | `deployment.airflow.providers` |
| `get_airflow_health` | Read | `deployment.airflow.health` |
| `get_airflow_component_health` | Read | `deployment.airflow.component_health` |
| `get_dag_stats` | Read | `deployment.airflow.dagstats` |
| `get_dag_run` | Read | `deployment.airflow.dagrun.get` |
| `get_dag_run_diagnosis` | Read | `deployment.airflow.dagrun.diagnose` |
| `check_upgrade_safety` | Read | None |

> [accordion] get\_task\_logs
>
> | Argument | Type | Required | Description |
> | - | - | - | - |
> | `deployment`, `dagId`, `dagRunId`, `taskId` | string | Yes | — |
> | `tryNumber` | integer | No | Defaults to the latest attempt. |
> | `mapIndex` | integer | No | Map index of a dynamically mapped task instance. |
> | `continuationToken` | string | No | From a prior response, to page forward. |

> [accordion] get\_import\_errors
>
> | Argument | Type | Required | Description |
> | - | - | - | - |
> | `deployment` | string | Yes | Whose Airflow import errors to report. |

> [accordion] get\_installed\_providers
>
> | Argument | Type | Required | Description |
> | - | - | - | - |
> | `deployment` | string | Yes | Whose installed Airflow providers to list. |

> [accordion] get\_airflow\_health
>
> | Argument | Type | Required | Description |
> | - | - | - | - |
> | `deployment` | string | Yes | Whose Airflow Dag-authoring health to report. |
>
> Reports Dag-authoring health: Airflow version, import errors, Dag warnings, and Dag run stats by state, with an overall healthy, warning, or unhealthy status. Dag run stats are available on Airflow 3 only.

> [accordion] get\_airflow\_component\_health
>
> | Argument | Type | Required | Description |
> | - | - | - | - |
> | `deployment` | string | Yes | Whose Airflow component liveness to report. |
>
> Reports process liveness for the metadata database, scheduler, triggerer, and, on Airflow 3, the Dag processor, each with a healthy or unhealthy status and its last heartbeat. Distinct from `get_airflow_health`, which reports Dag-authoring health.

> [accordion] get\_dag\_stats
>
> | Argument | Type | Required | Description |
> | - | - | - | - |
> | `deployment` | string | Yes | — |
> | `dagId` | string | No | Narrow to one Dag. |
> | `states` | array of strings | No | For example `["failed"]`. |
> | `limit` | integer | No | Max runs per Dag. Defaults to 10. |

> [accordion] get\_dag\_run
>
> | Argument | Type | Required | Description |
> | - | - | - | - |
> | `deployment`, `dagId`, `runId` | string | Yes | — |

> [accordion] get\_dag\_run\_diagnosis
>
> | Argument | Type | Required | Description |
> | - | - | - | - |
> | `deployment`, `dagId`, `runId` | string | Yes | — |
>
> Filters a run's task instances to the failed and upstream-failed ones.

> [accordion] check\_upgrade\_safety
>
> | Argument | Type | Required | Description |
> | - | - | - | - |
> | `currentVersion` | string | Yes | The currently installed Apache Airflow version, as a full semantic version (for example `2.10.5`). |
> | `targetVersion` | string | No | Omit to resolve the knowledge base's latest known version. |
> | `providers` | array | No | Each entry: `{package, version, target}`. |

## Airflow destroy (`airflow_destroy`, off by default)

Destructive Dag run and task-instance operations, in their own group so you can enable them independently of `platform_destroy`. All three call the Deployment's Airflow REST API through the APC API, so they work on both Helm-based and operator-based Deployments. None restarts a Deployment.

| Tool | Effect | MCP permission |
| - | - | - |
| `delete_dag_run` | Destroy | `deployment.airflow.dagrun.delete` |
| `clear_task_instances` | Destroy | `deployment.airflow.taskinstances.clear` |
| `clear_dag_run` | Destroy | `deployment.airflow.dagrun.clear` |

> [accordion] delete\_dag\_run
>
> | Argument | Type | Required | Description |
> | - | - | - | - |
> | `deployment`, `dagId`, `dagRunId` | string | Yes | — |
> | `confirm` | boolean | Yes | Must be explicitly `true`. Permanently deletes the run and all its task instances. |

> [accordion] clear\_task\_instances
>
> | Argument | Type | Required | Description |
> | - | - | - | - |
> | `deployment`, `dagId`, `runId` | string | Yes | — |
> | `taskIds` | array of strings | Yes | Every map index of a mapped task is cleared too. |
> | `confirm` | boolean | Yes | Must be explicitly `true`. |

> [accordion] clear\_dag\_run
>
> | Argument | Type | Required | Description |
> | - | - | - | - |
> | `deployment`, `dagId`, `runId` | string | Yes | — |
> | `confirm` | boolean | Yes | Must be explicitly `true`. Clears every task instance in the run and re-queues it. |

## Skills (`skills_load`, off by default)

Skill-delivery tools are read-only and carry no permission requirement of their own. They return vendored content, not platform state. `astronomer.mcpServer.skills.enabled` toggles them, and you don't list them in `enabledGroups`. See [Astro Private Cloud MCP server skills](https://astronomer.io/docs/astro-private-cloud/v-2-x/apc-mcp-server-skills.md) for how these combine with the per-skill prompts.

| Tool | Effect | MCP permission |
| - | - | - |
| `list_skills` | Read | None |
| `load_skill` | Read | None |
| `read_skill_file` | Read | None |

> [accordion] list\_skills
>
> No arguments. Returns every loadable skill, each with its name, description, and origin.

> [accordion] load\_skill
>
> | Argument | Type | Required | Description |
> | - | - | - | - |
> | `name` | string | Yes | The skill to load. Call `list_skills` for the available names. |

> [accordion] read\_skill\_file
>
> | Argument | Type | Required | Description |
> | - | - | - | - |
> | `skill` | string | Yes | The skill that owns the file. Call `list_skills` for the available names. |
> | `file` | string | Yes | The file's skill-relative path exactly as the skill body links it, for example `reference/config-changes.md`. |