> ## 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. # Connect a client to the Astro Private Cloud MCP server > Check availability, obtain a token, connect an AI agent client, and make your first tool call against 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](#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. > [!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. ## 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: ```graphql wrap theme={null} mutation createMcpClientServiceAccount { createWorkspaceServiceAccount( label: "my-mcp-client" workspaceUuid: "" role: WORKSPACE_VIEWER ) { id apiKey } } ``` Save the returned `apiKey` somewhere secure. It isn't shown again. See [Develop and test APC API queries](https://astronomer.io/docs/astro-private-cloud/v-2-x/houston-api-develop-test.md) 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](https://astronomer.io/docs/astro-private-cloud/v-2-x/houston-create-deployment-service-account.md). ## Connect a client The server's endpoint is `https://mcp-server./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. ```json VS Code (.vscode/mcp.json) wrap theme={null} { "servers": { "apc": { "type": "http", "url": "https://mcp-server./mcp", "headers": { "Authorization": "Bearer " } } } } ``` ```json Cursor (.cursor/mcp.json) wrap theme={null} { "mcpServers": { "apc": { "url": "https://mcp-server./mcp", "headers": { "Authorization": "Bearer " } } } } ``` ```json Claude Code (.mcp.json) wrap theme={null} { "mcpServers": { "apc": { "type": "http", "url": "https://mcp-server./mcp", "headers": { "Authorization": "Bearer " } } } } ``` 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. > [!WARNING] > > 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: ```json Call wrap theme={null} { "deployment": "" } ``` ```json Response (abbreviated) wrap theme={null} { "deployment": "", "label": "my-deployment", "status": "HEALTHY", "type": "DEDICATED", "runtimeVersion": "3.1-2", "airflowUrl": "https://my-deployment.", "config": { "defaultAirflowChartVersion": "...", "latestVersion": "...", "loggingEnabled": true }, "variables": [] } ``` A response means the gate authenticated your token and the APC API authorized the call. See the [runbook](https://astronomer.io/docs/astro-private-cloud/v-2-x/apc-mcp-server-runbook.md) 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](https://astronomer.io/docs/astro-private-cloud/v-2-x/apc-mcp-server-skills.md#invoke-a-skill), and client support for those is uneven. See the [client support table](https://astronomer.io/docs/astro-private-cloud/v-2-x/apc-mcp-server-skills.md#client-support) for which clients surface a skill prompt or fetch its reference documents, and the fallback for each gap.