Connect a client to the Astro Private Cloud MCP server

Connect an AI agent client to the Astro Private Cloud (APC) Model Context Protocol (MCP) server and make its first tool call. Check Availability first: a client pointed at an install on the wrong side of either axis below gets nothing, and the failure looks like a connection problem rather than an unsupported combination.

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.

Availability

Two independent axes determine whether the server works on your install and what it can do.

Deployment model

Deployment model	What you get
Operator-based	Everything: platform operations, Airflow task logs and diagnostics (import errors, installed providers, and health), Airflow state through the Laminar Airflow-state service, and skills.
Helm-based	Platform operations, plus Airflow task logs and diagnostics (import errors, installed providers, and health). The Airflow-state tools (`get_dag_stats`, `get_dag_run`, `get_dag_run_diagnosis`) and the `debugging-dags` skill are unsupported: the tools appear in the catalog but return an unsupported error for a Helm-based Deployment.

A single install can have both kinds of Deployment. The limit is per Deployment, not per cluster. Ask your System Admin which model a Deployment uses if you’re not sure.

Ingress model

Ingress model	Supported
Platform NGINX (the default)	Yes.
Bring-your-own-ingress (`global.authSidecar.enabled`)	No, not in this release. The chart refuses to enable the MCP server under bring-your-own-ingress at all, so this fails at install time rather than at connection time.
Istio Gateway (`global.istio.gateway.enabled`)	Not yet supported. An Istio Gateway requires the auth sidecar, so it falls under the same bring-your-own-ingress restriction.

If the server is enabled but you can’t reach it, confirm the ingress model before assuming your client is misconfigured.

Obtain a token

This release authenticates with a static service-account bearer token, the same kind the Astro CLI uses. There is no per-user OAuth flow yet. If the MCP server is enabled, you can copy the endpoint and create a connection token under Connect to MCP in the APC UI sidebar instead of running the mutation below. Admins can review which tool groups and skills are enabled under System > MCP Server. Use the narrowest service account that covers what the client needs. The MCP server applies APC API RBAC to every call, so the token’s role bindings limit what a client (or a skill it invokes) can reach, regardless of what it asks for. A Workspace user role and a Workspace-scoped service account behave differently:

A Workspace user role covers platform operations only (platform_read/platform_write).
A Workspace-scoped service account expands its role to the same tier on every Deployment in the Workspace, including Deployments created later. A Workspace Editor service account acts as a Deployment Editor on each Deployment, which reaches the Airflow-state tools (airflow_read/airflow_destroy) where those groups are enabled.

To limit a client to specific Deployments, create a Deployment-scoped service account instead. To create a Workspace-scoped service account, run the following through the APC API. Use WORKSPACE_VIEWER for read-only access or WORKSPACE_EDITOR for read and write access:

mutation createMcpClientServiceAccount {
  createWorkspaceServiceAccount(
    label: "my-mcp-client"
    workspaceUuid: "<your-workspace-id>"
    role: WORKSPACE_VIEWER
  ) {
    id
    apiKey
  }
}

Save the returned apiKey somewhere secure. It isn’t shown again. See Develop and test APC API queries to run this in your installation’s GraphQL playground. To scope the service account to a single Deployment instead, see Create a Deployment service account with the APC API.

Connect a client

The server’s endpoint is https://mcp-server.<your-base-domain>/mcp, reached over the platform’s existing ingress with the token above as a bearer credential. These examples were tested with VS Code 1.136.1 and Cursor 3.22.12.

{
  "servers": {
    "apc": {
      "type": "http",
      "url": "https://mcp-server.<your-base-domain>/mcp",
      "headers": {
        "Authorization": "Bearer <your-service-account-token>"
      }
    }
  }
}

{
  "mcpServers": {
    "apc": {
      "url": "https://mcp-server.<your-base-domain>/mcp",
      "headers": {
        "Authorization": "Bearer <your-service-account-token>"
      }
    }
  }
}

{
  "mcpServers": {
    "apc": {
      "type": "http",
      "url": "https://mcp-server.<your-base-domain>/mcp",
      "headers": {
        "Authorization": "Bearer <your-service-account-token>"
      }
    }
  }
}

Clients that let you set a static Authorization header (VS Code, Cursor, and Claude Code) fit this release’s token model directly. Claude Desktop reaches a remote MCP server through Settings > Connectors > Add custom connector rather than a project config file.

Don’t commit any of these files with a real token in it. Keep the token out of source control with your editor’s secret-input mechanism (VS Code’s inputs), an environment variable your shell injects, or a local file excluded from version control.

Make your first tool call

get_deployment is in the platform_read group, which is on by default, so it’s a safe first call against any enabled install. Ask the model for a Deployment’s detail, or call the tool directly if your client supports that:

{ "deployment": "<your-deployment-id>" }

{
  "deployment": "<your-deployment-id>",
  "label": "my-deployment",
  "status": "HEALTHY",
  "type": "DEDICATED",
  "runtimeVersion": "3.1-2",
  "airflowUrl": "https://my-deployment.<your-base-domain>",
  "config": { "defaultAirflowChartVersion": "...", "latestVersion": "...", "loggingEnabled": true },
  "variables": []
}

A response means the gate authenticated your token and the APC API authorized the call. See the runbook if you get an error instead.

Client support for skills

Tools (like get_deployment above) work in every MCP client. Prompts and resources are used only by skills, and client support for those is uneven. See the client support table for which clients surface a skill prompt or fetch its reference documents, and the fallback for each gap.

​Availability

​Deployment model

​Ingress model

​Obtain a token

​Connect a client

​Make your first tool call

​Client support for skills

Availability

Deployment model

Ingress model

Obtain a token

Connect a client

Make your first tool call

Client support for skills