MCP servers

Astro provides 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 the following MCP servers:

Astro MCP server (astro) is an authenticated remote MCP server for accessing your Astro control plane, including Deployments, Workspaces, environment objects, and Organization settings. It signs you in with your own Astro credentials and respects your existing permissions. This server replaces the deprecated Astro Cloud MCP server.
Astro Registry MCP server (astro-registry) is an experimental remote MCP server for accessing the Astro Registry.
Astro Cloud MCP server (astro-cloud) is deprecated and replaced by the Astro MCP server. See the following warning.

Astro Cloud MCP server deprecationThe Astro Cloud MCP server (astro-cloud) is deprecated and shouldn’t be used. It’s replaced by the Astro MCP server. Migrate any existing astro-cloud configuration to the new server. Unlike astro-cloud, which required an Organization ID and an API token, the Astro MCP server signs you in with your Astro credentials.

Set up the Astro MCP server

LabsThis feature is in Labs. Contact your account team to enable this feature.

The Astro MCP server currently provides read access to your Astro control plane: Deployments, Workspaces, environment objects (connections and variables), and Organization settings. It also provides Otto skills over the same connection, such as Airflow upgrade planning and the investigation agent.

Claude Code
Cursor
Claude Desktop
VS Code
Codex

Claude Code connects to remote MCP servers natively without the mcp-remote module.

claude mcp add --transport http astro https://api.astronomer.io/v1alpha1/astro/mcp

The first time you use a tool from the server, your client opens a browser window so you can sign in with your Astro credentials.

Open Cursor.
Navigate to Customize > New MCP server.

Add the following configuration:

{
  "mcpServers": {
    "astro": {
      "url": "https://api.astronomer.io/v1alpha1/astro/mcp"
    }
  }
}

Save the configuration, then sign in with your Astro credentials when prompted.

If you’re on a managed Claude account, a Claude Code admin must add the remote MCP server URL before you can add a custom connector

Open Claude Desktop settings.
Navigate to Connectors > Add custom connector.

Add the following configuration:

{
  "mcpServers": {
    "astro": {
      "url": "https://api.astronomer.io/v1alpha1/astro/mcp"
    }
  }
}

You can also connect through an internal AI gateway if your organization uses one. Contact your Astronomer account team for details.

Set up the Astro Registry MCP server

PreviewThis feature is in Preview.

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:

{
  "mcpServers": {
    "astro-registry": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.astronomer.io/registryV2/v1alpha1/mcp"
      ]
    }
  }
}

Click Save to save your configuration and check the Plugins section to verify that your server is connected.

Open Cursor.
Navigate to Tools & Integrations > Add Custom MCP.

Add the following configuration:

{
  "mcpServers": {
    "astro-registry": {
      "url": "https://api.astronomer.io/registryV2/v1alpha1/mcp"
    }
  }
}

Save the configuration and check the Tools & Integrations > MCP Servers section to verify that your server is connected.

Claude Code connects to remote MCP servers natively without the mcp-remote module. You can configure the server at the project level (.mcp.json) or at the user level (~/.claude.json).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

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

{
  "mcpServers": {
    "astro-registry": {
      "type": "http",
      "url": "https://api.astronomer.io/registryV2/v1alpha1/mcp"
    }
  }
}

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 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 Settings, then in the Access Management section, click Roles & Permissions, click Custom, then click + New Custom Role (in the legacy UI, go to Organization Settings > Access Management > Roles, then click + 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.config.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.

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>"
      }
    }
  }
}

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.

Overview

Get started

Develop DAGs

AI features

Deploy code

Manage Deployments

Automation & CI/CD

Platform observability

Administration

Release notes

Best practices

Reference

Airflow 3

MCP servers

MCP servers

Set up the Astro MCP server

Set up the Astro Registry MCP server

Airflow MCP plugin

Prerequisites

Install the plugin

Set environment variables

Configure authentication

Option A: Use a built-in role

Option B: Create a custom `MCP_VIEWER` role (recommended)

Connect your MCP client

Troubleshooting

​MCP servers

​Set up the Astro MCP server

​Set up the Astro Registry MCP server

​Airflow MCP plugin

​Prerequisites

​Install the plugin

​Set environment variables

​Configure authentication

​Option A: Use a built-in role

​Option B: Create a custom MCP_VIEWER role (recommended)

​Connect your MCP client

​Troubleshooting

MCP servers

Set up the Astro MCP server

Set up the Astro Registry MCP server

Airflow MCP plugin

Prerequisites

Install the plugin

Set environment variables

Configure authentication

Option A: Use a built-in role

Option B: Create a custom `MCP_VIEWER` role (recommended)

Connect your MCP client

Troubleshooting