MCP servers

Preview

This feature is in Preview.

Astro provides experimental Model Context Protocol (MCP) servers that allow AI models and agents to securely access your Astro and Airflow resources. Connect to MCP servers natively or by using the mcp-remote module in compatible AI clients.

For enhanced agent capabilities such as Dag authoring, testing, and debugging, see the Astronomer AI Agent tooling repository.

Astro provides two experimental MCP servers:

Astro Registry MCP server (astro-registry) is a remote MCP server for accessing the Astro Registry.
Astro Cloud MCP server (astro-cloud) is an authenticated remote MCP server for discovering and managing your Astro resources, including Deployments, Workspaces, and environment variables. The Astro Cloud MCP server follows the authenticated remote MCP specification, with the server centrally hosted and managed by Astronomer.

Setup Instructions

If you experience any issues, try restarting your client or disabling and re-enabling the Astro MCP server connection.

Windsurf

Cursor

Claude Code

Open Windsurf settings with CTRL/CMD + ,.
Navigate to Cascade > Manage plugins.
Select View raw config.

Add the following configuration. Only include the astro-cloud section if you’re using the authenticated Astro Cloud MCP server.

1 {
2   "mcpServers": {
3     "astro-registry": {
4       "command": "npx",
5       "args": [
6         "-y",
7         "mcp-remote",
8         "https://api.astronomer.io/registryV2/v1alpha1/mcp"
9       ]
10     },
11     "astro-cloud": {
12       "command": "npx",
13       "args": [
14         "-y",
15         "mcp-remote",
16         "https://api.astronomer.io/v1alpha1/mcp?organizationId=<MY_ORGANIZATION_ID>",
17         "--header",
18         "Authorization: Bearer ${AUTH_TOKEN}"
19       ],
20       "env": {
21         "AUTH_TOKEN": "<MY_AUTH_TOKEN>"
22       }
23     }
24   }
25 }

(If using Astro Cloud MCP) Find your Astro Organization ID in the Astro UI. Enter the ID as <MY_ORGANIZATION_ID> in the URL of the configuration above.
(If using Astro Cloud MCP) Create a Workspace or Organization token in the Astro UI. Enter the token as <MY_AUTH_TOKEN> in the "env" section of the configuration above.
Click Save to save your configuration and check the Plugins section to verify that your servers are connected.

Airflow MCP Plugin

The Airflow MCP Plugin (astro-airflow-mcp) is an open-source package that installs directly into an Airflow Deployment and exposes an MCP endpoint on the webserver. This gives AI tools direct access to Airflow’s REST API — Dags, task logs, connections, variables, and more — without running a separate server.

Unlike the Astro Cloud MCP server (which manages Astro-level resources like Deployments and Workspaces), the Airflow MCP Plugin provides Airflow-level access for a single Deployment: listing Dags, viewing task logs, inspecting connections, diagnosing failures, and more.

The plugin auto-detects the installed Airflow version and registers the appropriate integration:

Airflow 3.x: Mounts as a FastAPI app on the API server.
Airflow 2.x (2.4 or later): Registers as a Flask blueprint on the webserver.

Prerequisites

An Airflow Deployment on Astro. The plugin supports Airflow 3.x (Runtime 3.1 or later) and Airflow 2.x (2.4 or later).
A Deployment API token with a role that allows POST requests (required by the MCP protocol). See Configure authentication for role options.

Install the plugin

Add astro-airflow-mcp to your Astro project’s requirements.txt:

astro-airflow-mcp

Deploy the change. The package auto-registers as an Airflow plugin — no Dockerfile changes or additional configuration needed.

Set environment variables

After deploying, set the following environment variable on your Deployment to block write operations:

$ astro deployment variable create --deployment-id <DEPLOYMENT_ID> AF_READ_ONLY=true

Variable	Required	Description
`AF_READ_ONLY`	Recommended	Blocks all write operations (trigger, pause, clear, delete) at the MCP server level, regardless of the token’s permissions. Set to `true` for safe read-only access.

In plugin mode, the MCP server always runs in stateless HTTP mode, so Claude Code and other MCP clients work without additional configuration. The FASTMCP_STATELESS_HTTP environment variable applies only when running the MCP server as a standalone process.

Configure authentication

The MCP protocol uses POST requests for all operations, including read-only ones. Your Deployment API token does not need write permissions for read-only MCP access: authorization is still based on the underlying Airflow permissions, so a custom role with read permissions such as *.get is sufficient. The important exception is WORKSPACE_MEMBER, which Astro’s auth proxy blocks from making the POST requests the MCP protocol requires.

Option A: Use a built-in role

Create a Deployment API token with one of the following roles:

DEPLOYMENT_ADMIN — Full access (works but overprivileged)
WORKSPACE_OPERATOR or WORKSPACE_AUTHOR — Moderate privilege

WORKSPACE_MEMBER does not work with the MCP plugin. Astro’s auth proxy blocks POST requests for this role, which prevents the MCP protocol handshake from completing.

Option B: Create a custom MCP_VIEWER role (recommended)

For least-privilege access, create a custom Deployment role that includes only read permissions. This ensures the token can use all MCP read tools but cannot modify any Airflow resources.

In the Astro UI, go to Organization Settings > Access Management > Roles > + Add Role.
Set the Scope to Deployment.
Name the role MCP_VIEWER with a description like “Read-only access for Airflow MCP plugin.”

Select all deployment.airflow.*.get permissions. See Custom role permissions reference for the full list. The role should include these 28 permissions:

Permission	Purpose
`deployment.get`	Get Deployment information
`deployment.airflow.adminMenu.get`	View Admin menu (gates Airflow config API)
`deployment.airflow.astronomer.get`	View Astronomer menu
`deployment.airflow.auditLog.get`	View audit logs
`deployment.airflow.browseMenu.get`	View Browse menu
`deployment.airflow.clusterActivity.get`	View cluster activity and DAG stats
`deployment.airflow.configMenu.get`	View Config menu
`deployment.airflow.connection.get`	View connections
`deployment.airflow.customMenu.get`	View custom plugin menus
`deployment.airflow.dag.get`	View Dags
`deployment.airflow.dagCode.get`	View DAG source code
`deployment.airflow.dagDependencies.get`	View DAG dependencies
`deployment.airflow.dagRun.get`	View DAG runs
`deployment.airflow.datasets.get`	View assets and datasets
`deployment.airflow.docs.get`	View documentation links
`deployment.airflow.importError.get`	View import errors
`deployment.airflow.job.get`	View scheduler jobs
`deployment.airflow.plugin.get`	View plugins
`deployment.airflow.pool.get`	View pools
`deployment.airflow.provider.get`	View providers
`deployment.airflow.slaMiss.get`	View SLA misses
`deployment.airflow.taskInstance.get`	View task instances
`deployment.airflow.taskLog.get`	View task logs
`deployment.airflow.taskReschedule.get`	View task reschedules
`deployment.airflow.trigger.get`	View triggers
`deployment.airflow.variable.get`	View variables
`deployment.airflow.website.get`	Access the Airflow UI
`deployment.airflow.xcom.get`	View XCom data

Click Create role.

Then create a Deployment API token with the new role:

$ astro deployment token create \
>   --deployment-id <DEPLOYMENT_ID> \
>   --name "mcp-viewer" \
>   --role MCP_VIEWER

Connect your MCP client

After the plugin is deployed and a token is created, the MCP endpoint is available at:

https://<DEPLOYMENT_WEBSERVER_URL>/mcp/v1/

You can find your Deployment’s webserver URL in the Astro UI on the Deployment’s overview page.

Claude Code

Cursor

VS Code / Other Clients

$ claude mcp add -t http -s user \
>   -H "Authorization: Bearer <TOKEN>" \
>   -- airflow \
>   "https://<DEPLOYMENT_WEBSERVER_URL>/mcp/v1/"

Use -t http, not -t sse. The MCP endpoint returns SSE-formatted responses, but the correct Claude Code transport type is http. Using -t sse causes the connection to fail.

Troubleshooting

Symptom	Cause	Fix
`Failed to connect` with `-t sse`	Wrong transport type	Use `-t http` instead of `-t sse` in Claude Code
401 Unauthorized on MCP endpoint	Missing or expired token	Regenerate the Deployment API token
403 Forbidden on some read tools	Incomplete role permissions	Ensure the role includes all `deployment.airflow.*.get` permissions listed above
403 on `get_airflow_config` or `list_dag_warnings`	Airflow Admin RBAC required	A small number of Airflow API endpoints require the Admin role regardless of Astro permissions. Most MCP tools work without Admin access.
WORKSPACE_MEMBER token fails	POST blocked by Astro auth proxy	Use a higher-privilege role or create a custom `MCP_VIEWER` role
404 on MCP endpoint right after a deploy	Plugin loads per-worker, rolling restart in progress	Wait for the rollout to settle, then retry. The first MCP call per worker also adds a small one-time latency while the FastMCP lifespan warms up.