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 from compatible AI clients. To give an agent access to the Astronomer documentation instead of your Astro resources, see Use these docs with AI. 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 reading your Astro resources, including Deployments, Workspaces, environment objects, and Organization settings, and the Dags, Dag runs, and Airflow REST API of your Deployments. It signs you in with your own Astro credentials and respects your existing permissions. This server replaces the deprecated Astro Cloud MCP server.
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 and is available to all Astro Organizations.

The Astro MCP server provides read access to your Astro resources and to the Airflow environment of each Deployment you can access. It can also start Otto investigations of failed Dag runs and send feedback to Astronomer. It provides the following tools:

Tool	Description
`get_organization`	Get Organization details, including plan, status, and security settings such as SCIM and IP address allowlists.
`list_workspaces`	List the Workspaces in an Organization, with each Workspace’s description, CI/CD enforcement default, and default cloud provider, region, and cluster.
`get_workspace`	Get Workspace details, including whether new Deployments enforce CI/CD by default and the default cloud provider, region, and cluster.
`list_clusters`	List the clusters in an Organization, with each cluster’s cloud provider, region, type, status, health, node pools, and network ranges.
`get_cluster`	Get cluster details, including node pools, network ranges, disaster recovery settings, and the Workspaces the cluster is assigned to.
`list_deployments`	List the Deployments you can access, with each Deployment’s status, Astro Runtime and Airflow versions, executor, and scaling settings.
`get_deployment`	Get Deployment details, including worker queues, default task Pod resources, resource quotas, and the cluster, cloud provider, and region it runs in.
`list_deploys`	List the deploys of a Deployment, with each deploy’s type, status, image tag, Dag bundle version, Astro Runtime and Airflow versions, Git metadata, and author.
`get_deploy`	Get the details of one deploy of a Deployment.
`get_deployment_logs`	Search the Airflow component logs of a Deployment, such as scheduler, worker, or API server logs, for a time window of up to 24 hours.
`list_environment_objects`	List the Airflow connections, Airflow variables, environment variables, and metrics exports in a Workspace or Deployment. Secret values are hidden by default.
`get_environment_object`	Get the details of one environment object, including its scope and links. Secret values are always hidden.
`list_dags`	List the Dags in a Deployment, with each Dag’s paused state, import errors, and schedule.
`get_dag`	Get the details of one Dag, including its paused state, import errors, schedule, owners, tags, and next scheduled run.
`list_dag_runs`	List the runs of a Dag, filtered by state or date range.
`get_task_logs`	Read the log of one task try in a Deployment. Returns the end of the log and any error lines and stack traces, and can page back through longer logs. Requires permission to view task logs in the Deployment.
`search_airflow_api`	Search the read operations of the Airflow REST API for the Airflow version that a Deployment runs.
`get_airflow_api`	Call a read operation of a Deployment’s Airflow REST API, such as getting a Dag or listing task instances for a Dag run.
`list_skills`	List the Otto skills available to your Organization, such as Airflow upgrade planning, Dag debugging, and Dag authoring.
`start_investigation`	Start an Otto investigation of a failed Dag run, or of one task in the run. If the same failure already has an investigation, returns that investigation.
`get_investigation`	Get the status of an Otto investigation: pending, running, completed, failed, or timed out.
`get_investigation_diagnosis_result`	Get the diagnosis of a completed Otto investigation, including its title, summary, root cause, suggested fix, and evidence.
`submit_feedback`	Send a bug report, friction report, or feature request about Astro or the Astro MCP server to Astronomer.

The Astro MCP server signs you in with your Astro credentials, so each tool returns only the resources that your existing permissions allow you to view. The investigation tools are available only to Organizations that have Otto investigations enabled. They require permission to view task logs for the whole Deployment. A Dag-level role isn’t enough.

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

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

To authenticate, run /mcp in Claude Code and select the astro server. Claude Code 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/labs/v1/astro/mcp"
    }
  }
}

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

Add the Astro MCP server to Claude as a custom connector. Claude connects to the server from Anthropic’s servers, so a connector that you add works in Claude on the web, Claude Desktop, and Cowork.The Astro MCP server supports only Dynamic Client Registration. When you add the connector, you must select Register automatically under OAuth client. The default option, Use Claude’s published identity (Recommended), doesn’t work with the Astro MCP server.On a Claude Pro or Max plan, add the connector yourself:

In Claude, go to Customize > Connectors.
Click + Add, then click Add custom connector.
For the name, enter Astro.
For the remote MCP server URL, enter https://api.astronomer.io/labs/v1/astro/mcp. Click Continue.
Under Authentication, select Sign in now or Sign in when needed.
Under OAuth client, select Register automatically.
Click Add.
Click Connect for the Astro connector, then sign in with your Astro credentials.

On a Claude Team or Enterprise plan, an Owner of your Claude organization adds the connector:

In Claude, go to Organization settings > Connectors.
Click Add, then select Custom > Web.
Enter the same name, URL, Authentication, and OAuth client values as in the Pro and Max steps, then click Add.

After the Owner adds the connector, each member goes to Customize > Connectors, clicks Connect for the Astro connector, and signs in with their Astro credentials.To use the connector in a conversation, click + in the chat, select Connectors, and turn on Astro.

The Code tab of the Claude Desktop app can’t sign in to the Astro MCP server at this time, because it uses a claude:// callback that the server doesn’t accept. Use a custom connector in the chat side of Claude, or add the server to the Claude Code CLI with claude mcp add, as described in the Claude Code tab.

Go to the Command Palette.
Select MCP: Add Server.
Select HTTP and set the URL to https://api.astronomer.io/labs/v1/astro/mcp.
Authenticate the MCP.

Go to Plugins.
Select Add > Add MCP Server.
Select Streamable HTTP and set the URL to https://api.astronomer.io/labs/v1/astro/mcp.
Authenticate the MCP.

Open your OpenCode config file, opencode.json.

Add the following configuration:

{
  "mcp": {
    "astro": {
      "type": "remote",
      "url": "https://api.astronomer.io/labs/v1/astro/mcp"
    }
  }
}

Save the configuration, then run opencode mcp auth astro and sign in with your Astro credentials.

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

Authenticate with an API token

Instead of signing in through a browser, you can authenticate with an Organization API token, a Workspace API token, or a Deployment API token. Use this option for automated agents and other clients that can’t complete a browser sign-in. Send the token in the Authorization header. For example, in Claude Code:

claude mcp add --transport http astro https://api.astronomer.io/labs/v1/astro/mcp \
  --header "Authorization: Bearer <api-token>"

The MCP server tools return only the resources that the token’s role allows. To limit an agent to read access, assign the token a role without write permissions.

Approve redirect URIs for MCP clients

LabsThis feature is in Labs and is available to all Astro Organizations.

When you sign in to an MCP client with OAuth, Astro sends the authorization code to the client’s redirect URI, the HTTPS URL that the client sends you back to. The resulting token reaches every Organization you belong to, so Astro sends the code only after all of those Organizations approve the redirect URI, and only after you confirm the sign-in. Astro approves some clients by default, including Claude.ai and local clients, so most people can connect without any setup. Approve a redirect URI when your users connect through a client that Astro doesn’t already approve, such as an MCP client that your company builds or hosts.

Prerequisites

Organization Owner permissions to approve or remove a redirect URI. Any Organization member can view the approved list.

Approve a redirect URI

In the Astro UI, go to Settings, then in the Security section, click MCP Redirect URIs.
Click + New Redirect URI.
Enter the exact HTTPS URL that the MCP client sends users back to, then click Approve Redirect URI.

Approve only redirect URIs that your company controls. After you approve a URI, any user in your Organization can complete an OAuth sign-in that delivers an authorization code to that URL, and the token it produces carries that user’s Astro permissions.

A redirect URI must be an exact HTTPS URL, such as https://mcp-client.example.com/oauth/callback. Astro rejects a URL that contains a wildcard, a fragment, or user information. Each Organization can approve up to 100 redirect URIs. To stop accepting a client, remove its redirect URI from the same page. Removing a URI immediately blocks new sign-ins through that URL, but a client that’s already signed in keeps its access until its token expires.

If a redirect URI isn’t approved

If any Organization you belong to hasn’t approved the client’s redirect URI, Astro doesn’t send the authorization code and shows you which Organizations still need to approve it. Ask an Organization Owner in each one to approve the URI, then sign in again.

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 provides read access across all Deployments you can access and signs you in with your Astro credentials, the Airflow MCP plugin runs inside a single Deployment and authenticates with a Deployment API token. It provides Airflow-level access for that 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.
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.

MCP servers

Set up the Astro MCP server

Authenticate with an API token

Approve redirect URIs for MCP clients

Prerequisites

Approve a redirect URI

If a redirect URI isn’t approved

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

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