Connecting AI Clients to Airflow MCP

Register the Airflow MCP endpoint in an AI client, such as Claude Desktop, Cursor or MCP Inspector, so the client can use Airflow MCP tools with your Data Fabric identity.

Before you begin

  • Make sure an administrator has turned on Airflow MCP. See Enabling Airflow MCP.

  • Get these details from your administrator:

    • The Airflow MCP endpoint URL:https://<mcp_host>:5679/airflow

    • For SSO (OAuth): an OAuth client ID and client secret.

    • For Basic authentication: your Data Fabric username and password.

  • Install Node.js, which includes npx, on the client machine.

  • Set up the client machine to trust the cluster's certificates:

    1. Copy /opt/mapr/conf/ssl_truststore.pem from a Data Fabric cluster node to the client machine.

    2. Note the file path. You'll use it for NODE_EXTRA_CA_CERTS in the steps below.

Choose an authentication method

Method When to use it How the client sends credentials
SSO (OAuth) Keycloak SSO is set up (recommended) mcp-remote with --static-oauth-client-info, or a Bearer JWT in MCP Inspector
Basic SSO isn't available An Authorization: Basic <token> header

Connecting Claude Desktop

With SSO (OAuth)

  1. In Claude Desktop, go to Settings > Developer > Edit Config.

  2. Open claude_desktop_config.json.

  3. Create a credentials file with limited permissions (for example, chmod 600). Put the OAuth client details in it:
    {
  "client_id": "<client_id>",
  "client_secret": "<client_secret>"
}
  4. Add the Airflow MCP server entry:
    {
  "mcpServers": {
    "<server_name>": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://<mcp_host>:5679/airflow",
        "--static-oauth-client-info",
        "</path/to/oauth_credentials.json>"
      ],
      "env": {
        "NODE_EXTRA_CA_CERTS": "</path/to/ssl_truststore.pem>"
      }
    }
  }
}
    You can also give the client details as a JSON string instead of a file path. For example:
    "{\"client_id\":\"<client_id>\",\"client_secret\":\"<client_secret>\"}"
    A file is recommended so the secret doesn't sit in the client config.

  5. Save the file and restart Claude Desktop.

With Basic authentication

  1. Encode your username and password in Base64:
    echo -n "<username>:<password>" | base64
  2. In claude_desktop_config.json, add the server entry with a Basic header:
    {
  "mcpServers": {
    "<server_name>": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://<mcp_host>:5679/airflow",
        "--header",
        "Authorization: Basic <encoded_token>"
      ],
      "env": {
        "NODE_EXTRA_CA_CERTS": "</path/to/ssl_truststore.pem>"
      }
    }
  }
}
  3. Save the file and restart Claude Desktop.
    NOTE
    Anyone who can read the Base64 token can decode it. Protect the config file and only connect over HTTPS.

Connecting Cursor

  1. In Cursor, go to Settings > Cursor Settings > MCP & Integrations > New MCP Server.

  2. Add the same JSON entry as for Claude Desktop, using either the SSO (OAuth) or the Basic authentication version.

  3. Save the JSON configuration file.

Connecting MCP Inspector

MCP Inspector is useful for testing the connection and trying tools before you use an AI assistant.
  1. Set NODE_EXTRA_CA_CERTS, then start MCP Inspector.
    Linux/macOS:
         export NODE_EXTRA_CA_CERTS=</path/to/ssl_truststore.pem>
     npx @modelcontextprotocol/inspector@latest
    Windows:
         set NODE_EXTRA_CA_CERTS="<C:\path\to\ssl_truststore.pem>"
     npx @modelcontextprotocol/inspector@latest
  2. Set the URL to https://<mcp_host>:5679/airflow.
  3. Select the Authentication tab and set Header name to Authorization.
  4. Enter the credentials:

    SSO: Enter your JWT as the Bearer token.

    Basic: Enter Basic <encoded_token> as the header value. This requires MCP Inspector 0.16.8 or later. Earlier versions only send a Bearer header.

  5. Click Connect.

Checking the connection

After you connect, check that the client lists the Airflow MCP tools. In MCP Inspector, click List Tools. Airflow MCP should return 33 tools.

To try it out, ask your AI client a read-only question, such as "What version of Airflow is running?" (getAirflowVersion) or "List my DAGs" (listDags).

Troubleshooting connection problems

Symptom Likely cause Fix
DEPTH_ZERO_SELF_SIGNED_CERT or another certificate error The client doesn't trust the cluster's certificate authority Set NODE_EXTRA_CA_CERTS to the copied ssl_truststore.pem and restart the client
HTTP 404 on /airflow Airflow MCP isn't turned on Ask an administrator to set airflow.enabled = true
401 errors with Basic authentication in MCP Inspector MCP Inspector is n earlier version than 0.16.8 and sends a Bearer header Upgrade MCP Inspector
401 errors with Basic authentication in Claude Desktop or Cursor The token isn't encoded correctly Encode it again with echo -n so there's no newline at the end
CAUTION
Do not set NODE_TLS_REJECT_UNAUTHORIZED=0 to work around certificate errors in production environments. It turns off TLS certificate checks completely.