Airflow MCP Prerequsities

Check that your cluster, user accounts and client machine meet these requirements before you turn on Airflow MCP and connect an AI client.

Cluster requirements

  • Cluster must be running on Data Fabric 8.2.0 or later and DEP 8.2.0 or later.
  • Data Access Gateway must be installed and running. The Data Fabric MCP server runs inside the Data Access Gateway and listens on port 5679 by default.
  • Airflow must be installed and running on the cluster.
  • The Data Access Gateway node must be able to reach the Airflow REST API. By default, the MCP server finds the Airflow service by itself. If it is unable to find the Airflow service, an administrator can set the Airflow REST URL.
  • The cluster must be secure, with TLS certificates set up. The MCP server uses the cluster's certificates.

Authentication requirements

  • Keycloak single sign-on must be set up for the cluster. Airflow MCP sends your JWT identity to Airflow as a Bearer token, so Airflow must accept Keycloak-issued tokens.
  • Clients that sign in with SSO need an OAuth client ID and client secret. They pass these to the MCP server through mcp-remote.
  • To use basic authentication with SSO turned off, you must have a Data Fabric username and password (airflow.auth.use-internal-jwt), which you encode as a Base64 token.
NOTE
Airflow MCP can also use Airflow's own username and password (airflow.auth.use-internal-jwt) when Keycloak isn't available. This option is only for development and testing. It is not to be used in production environments.

User requirements

  • Airflow permissions - each user needs permission in Airflow for the actions they ask the AI client to take. Airflow MCP runs every action as the user who asks for it, so it can't do anything the user couldn't do in Airflow.
  • run_as_user setting - before a user starts an Airflow DAG, the MCP server checks the run_as_user value set on the DAG and its tasks. If a DAG has a fixed run_as_user that doesn't match the user, the request is rejected. DAG authors should either leave run_as_user unset or set it to the users who will start the DAG.
  • DAG upload - users who publish DAGs through the AI client need permission to upload DAGs to Airflow. By default, a DAG file can be up to 10 MB.

Administrator tasks

An Administrator must complete these tasks before anyone can use Airflow MCP:
  1. Turn on Airflow MCP (it is off by default).
  2. (Optional) - set the Airflow REST URL, DAG upload limits and staging folder.
  3. Give users the OAuth client credentials or Basic authentication details, plus the MCP endpoint URL: https://<host>:5679/airflow.

Client machine requirements

  • An AI client that supports MCP, such as:
    • Claude Desktop
    • Cursor
    • MCP Inspector. To use Basic authentication, you must have version 0.16.8 or later, because earlier versions can only send Bearer headers.
  • Node.js with npx - needed to run mcp-remote for Claude Desktop and Cursor, and to start MCP Inspector.
  • Cluster trust store - copy /opt/mapr/conf/ssl_truststore.pem from a cluster node to the client machine. Then point the NODE_EXTRA_CA_CERTS environment variable at the file.
    CAUTION
    Do not set NODE_TLS_REJECT_UNAUTHORIZED=0 to work around certificate errors in production. It turns off TLS checks. Use NODE_EXTRA_CA_CERTS with the cluster trust store instead.