Astro MCP servers

Connect AI tools to Astro and Airflow using Model Context Protocol (MCP) servers

Public Preview

This feature is in

Public 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 these 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.

Available MCP servers

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

1. Open Windsurf settings with CTRL/CMD + ,.
2. Navigate to Cascade > Manage plugins.
3. Select View raw config.
4. Add the following configuration. Only include the astro-cloud section if you’re using the authenticated Astro Cloud MCP server.
   {
     "mcpServers": {
       "astro-registry": {
         "command": "npx",
         "args": [
           "-y",
           "mcp-remote",
           "https://api.astronomer.io/registryV2/v1alpha1/mcp"
         ]
       },
       "astro-cloud": {
         "command": "npx",
         "args": [
           "-y",
           "mcp-remote",
           "https://api.astronomer.io/v1alpha1/mcp?organizationId=<MY_ORGANIZATION_ID>",
           "--header",
           "Authorization: Bearer ${AUTH_TOKEN}"
         ],
         "env": {
           "AUTH_TOKEN": "<MY_AUTH_TOKEN>"
         }
       }
     }
   }
   
5. (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.
6. (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.
7. Click Save to save your configuration and check the Plugins section to verify that your servers are connected.

Cursor

1. Open Cursor.
2. Navigate to Tools & Integrations > Add Custom MCP.
3. Add the following configuration. Only include the astro-cloud section if you’re using the authenticated Astro Cloud MCP server.
   {
     "mcpServers": {
       "astro-registry": {
         "url": "https://api.astronomer.io/registryV2/v1alpha1/mcp"
       },
       "astro-cloud": {
         "url": "https://api.astronomer.io/v1alpha1/mcp?organizationId=<MY_ORGANIZATION_ID>",
         "headers": {
           "Authorization":"Bearer <MY_AUTH_TOKEN>"
         }
       }
     }
   }
   
4. (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.
5. (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 Custom MCP configuration you added previously.
6. Save the configuration and check the Tools & Integrations > MCP Servers section to verify that your servers are connected.

Claude Code

Claude Code connects to remote MCP servers natively without the mcp-remote module. You can configure the servers at the project level (.mcp.json) or at the user level (~/.claude.json).

If you have the

Astro CLI

installed and authenticated, you can paste the URL of this page into Claude Code and ask it to configure the Astro MCP servers. Claude Code can use

astro organization list

to retrieve your Organization ID and guide you through token creation.

Add the Astro Registry MCP server

The Astro Registry MCP server is public and requires no authentication. Run the following command to add it to your project:

claude mcp add --transport http --scope project astro-registry \
  https://api.astronomer.io/registryV2/v1alpha1/mcp

Add the Astro Cloud MCP server

The Astro Cloud MCP server requires your Organization ID and an API token.

1. Retrieve your Organization ID
2. If you have the Astro CLI installed and authenticated, run astro organization list to find your Organization ID. Otherwise, open the Astro UI and copy your Organization ID from Settings > General.
3. Create an API token
4. Create a Workspace or Organization API token in the Astro UI.
5. Set the token as an environment variable
6. Add the following to your shell profile (.zshrc, .bashrc, or equivalent) so it persists across sessions:
7. export ASTRO_AUTH_TOKEN=<your-token>
   

8. Add the server
9. Run the following command, replacing <your-organization-id> with the Organization ID you retrieved earlier:
10. claude mcp add --transport http --scope project astro-cloud \
      "https://api.astronomer.io/v1alpha1/mcp?organizationId=<your-organization-id>" \
      --header "Authorization: Bearer ${ASTRO_AUTH_TOKEN}"
    

11. Verify the connection
12. Run claude mcp list and confirm both astro-registry and astro-cloud appear.

The resulting .mcp.json file should look similar to the following:

{
  "mcpServers": {
    "astro-registry": {
      "type": "http",
      "url": "https://api.astronomer.io/registryV2/v1alpha1/mcp"
    },
    "astro-cloud": {
      "type": "http",
      "url": "https://api.astronomer.io/v1alpha1/mcp?organizationId=<your-organization-id>",
      "headers": {
        "Authorization": "Bearer ${ASTRO_AUTH_TOKEN}"
      }
    }
  }
}

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.

1. In the Astro UI, go to Organization Settings > Access Management > Roles > + Add Role.

2. Set the Scope to Deployment.

3. Name the role MCP_VIEWER with a description like “Read-only access for Airflow MCP plugin.”

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

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

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.

Cursor

Add the following to your MCP configuration in Cursor (Tools & Integrations > Add Custom MCP):

{
  "mcpServers": {
    "airflow": {
      "url": "https://<DEPLOYMENT_WEBSERVER_URL>/mcp/v1/",
      "headers": {
        "Authorization": "Bearer <TOKEN>"
      }
    }
  }
}

VS Code / Other Clients

Add the following to your MCP client configuration file:

{
  "mcpServers": {
    "airflow": {
      "url": "https://<DEPLOYMENT_WEBSERVER_URL>/mcp/v1/",
      "headers": {
        "Authorization": "Bearer <TOKEN>"
      }
    }
  }
}

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.