Airflow MCP security and authentication

Airflow MCP authenticates both the AI client and the calls it makes to Airflow. It runs every action as the user who asked for it, blocks user impersonation, requires a person to approve AI-written DAGs, and encrypts traffic with the cluster's TLS certificates.

Security model

Layer What protects it Default
AI client → MCP server SSO (OAuth/JWT) or Basic authentication Authentication on
MCP server → Airflow The user's JWT, sent to Airflow as a Bearer token JWT passthrough
Starting DAGs run_as_user impersonation check Check on
Creating DAGs Two-step review and upload Always on
Network TLS using the cluster's certificates HTTPS on port 5679

Client authentication to the MCP server

The Data Fabric MCP server turns on authentication by default for all its endpoints, including /airflow. Clients can sign in in two ways.

SSO (OAuth)

When Keycloak SSO is set up, clients get a JWT for the user and send it in an Authorization: Bearer <JWT> header. Claude Desktop and Cursor use mcp-remote, which takes the OAuth client ID and secret through --static-oauth-client-info. You can give them as a path to a JSON file or as a JSON string written straight into the config.
TIP
Keep OAuth client credentials in a separate file with limited permissions, rather than writing them into the client configuration.

Basic authentication

If SSO isn't available, clients can send an Authorization: Basic <token> header. The token is the Data Fabric username and password, joined as username:password and encoded in Base64:
echo -n "<username>:<password>" | base64
MCP Inspector requires version 0.16.8 or later for Basic authentication. Earlier versions only send a Bearer header.
NOTE
Base64 isn't encryption, so anyone who gets the token can decode it. Only use Basic authentication over TLS, and protect any config file that holds the token.

Turning off MCP server authentication

Administrators can turn off authentication by setting mcp.http.auth.enabled = false in mcp-server.conf:
mcp = {
  http = {
    auth = {
      enabled = false
    }
  }
}
WARNING
This setting turns off authentication for every Data Fabric MCP endpoint, not just Airflow. Do not use this setting in production environments.

MCP server authentication to Airflow

Passing through he user's JWT (default)

By default, Airflow MCP sends the user's JWT to Airflow as a Bearer token. Each action runs in Airflow as that user, under that user's Airflow permissions. The AI client can't do anything the user couldn't do in Airflow. No configuration is needed.

Airflow's own credentials (development and testing only)

For development or test setups without Keycloak, Airflow MCP can sign in to Airflow with a fixed Airflow account:

airflow {
  enabled = true
  auth = {
    use-internal-jwt = true
    username = <airflow_username>
    password = <airflow_password>
  }
}
WARNING
Do not use this in production environments. Requests reach Airflow as the account set here, not as the MCP user, and the password is stored as plain text in mcp-server.conf.

User impersonation protection

An Airflow DAG can set a run_as_user value on the DAG itself or on its tasks. Before starting a DAG, Airflow MCP checks that this value matches the user making the MCP request. If it doesn't match, the request is rejected. This stops users from asking an AI client to run workloads as a different user.

Guidance for DAG authors:
  • If a DAG will be started through Airflow MCP, do not set run_as_user to a fixed service account unless the only people who start the DAG are that account.
  • If a DAG needs to run as the person who started it, let the MCP client pass the user in the run_as_user parameter.
Administrators can turn off the check with
mcp.airflow.skip-run-as-user-check = true
WARNING
Only turn off this check in development or test environments. Without it, MCP users can start DAGs that run as other users.

Human review of AI-written DAGs

Airflow MCP never writes DAG code to Airflow on its own. Publishing a DAG requires the following steps:
  1. reviewDagForUpload saves the proposed Python code to a staging file and returns a short-lived reviewToken.
  2. The user checks the code and the target file name, then approves them.
  3. uploadDag uses the reviewToken to upload the DAG to Airflow's /dags/upload endpoint.
Staged files are kept in mcp.airflow.dag-review-temp-dir, with permissions set by mcp.airflow.dag-stage-file-permissions (default rw-------, so only the Data Access Gateway service user can read them). Files larger than mcp.airflow.dag-upload-max-size-bytes (default 10 MB) are rejected.
TIP
Treat AI-written DAG code the same way you would treat coe from a new contributor. Check its imports imports, connections, variables and any shell or Python operators before you approve it.

Tools that change or delete data

Some tools change the state of Airflow:

  • Delete data:deleteDagRun

  • Clear runs or tasks so they run again:clearDagRun, clearTaskInstances

  • Change the schedule:pauseDag, unpauseDag

  • Start runs:triggerDag, triggerDagAndWait

  • Publish a DAG:uploadDag

Set up your AI client to ask for your approval before it runs these tools, and read each request before you approve it.

TLS

The Data Fabric MCP server listens over HTTPS and uses the same certificates as the other cluster services:

  • Keystore (private keys):/opt/mapr/conf/ssl_keystore.*

  • Truststore (CA certificates):/opt/mapr/conf/ssl_truststore.*

By default, Data Fabric uses self-signed certificates. MCP clients such as Claude Desktop, Cursor and MCP Inspector reject these unless you tell them to trust the cluster's CA. If they don't trust it, you'll see errors such as DEPTH_ZERO_SELF_SIGNED_CERT.

Setting up clients to trust the cluster CA

  1. Copy /opt/mapr/conf/ssl_truststore.pem from a Data Fabric cluster node to the client machine.
  2. Set NODE_EXTRA_CA_CERTS to the path of the file.

    • MCP Inspector: set the variable before you start the inspector.

      • Linux/macOS: 
        export NODE_EXTRA_CA_CERTS=</path/to/ssl_truststore.pem>
      • Windows: 
        set NODE_EXTRA_CA_CERTS="<C:\path\to\ssl_truststore.pem>"

    • Claude Desktop and Cursor: add the variable to the env section of the MCP server entry:

         "env":
              { 
            "NODE_EXTRA_CA_CERTS": "</path/to/ssl_truststore.pem>" 
      }
  3. Restart the client.
    CAUTION
    Setting NODE_TLS_REJECT_UNAUTHORIZED=0 also gets rid of certificate errors, but it turns off certificate checks completely. That leaves the connection open to man-in-the-middle attacks. Do not use it in production environments.

Token introspection (RFC 7662)

The Data Fabric MCP server enforces live OAuth 2.0 token introspection (RFC 7662) against Keycloak to verify that user sessions and access tokens remain active before executing Airflow tool calls.

For complete details on token introspection behavior and configuration properties, see Configuring token introspection for MCP

Production security checklist

  • [ ] Keycloak SSO is set up, and MCP server authentication is on.

  • [ ] airflow.auth.use-internal-jwt isn't set, or is false.

  • [ ] mcp.airflow.skip-run-as-user-check isn't set, or is false.

  • [ ] Clients trust the cluster CA through NODE_EXTRA_CA_CERTS, not NODE_TLS_REJECT_UNAUTHORIZED=0.

  • [ ] OAuth client secrets and Basic tokens are kept in files with limited permissions.

  • [ ] Users have only the Airflow permissions they need.

  • [ ] AI clients ask for approval before running tools that change or delete data.