Authentication Mechanisms Supported for Streamable-HTTP Transport Mode in MCP Airflow API

The streamable-http transport mode in call518/mcp-airflow-api supports optional Bearer token authentication via FastMCP's static token verifier, or can run without authentication for open access.

The streamable-http transport mode provides HTTP-based communication for the MCP (Model Context Protocol) Airflow API server. Understanding the authentication mechanisms supported for streamable-http transport mode is critical for securing your deployment. The implementation in src/mcp_airflow_api/mcp_main.py offers two distinct operational modes: authenticated access using static Bearer tokens, or unauthenticated open access.

Bearer Token Authentication for Streamable-HTTP

The primary authentication mechanism supported for streamable-http transport mode is static Bearer token authentication using FastMCP's StaticTokenVerifier.

Enabling Static Token Verification

To enable authentication, you must explicitly activate it via command-line flags or environment variables. The server checks for the --auth-enable flag or REMOTE_AUTH_ENABLE=true environment variable in the main() function (lines 46-63) of src/mcp_airflow_api/mcp_main.py.

When enabled, the server initializes the _build_static_token_auth function (lines 45-52), which constructs a token map and instantiates StaticTokenVerifier:

tokens = {secret_key: {"client_id": "airflow-api-client","scopes": ["read","write"]}}
return StaticTokenVerifier(tokens=tokens)

Configuration Options

You must provide a secret key through either the --secret-key CLI argument or the REMOTE_SECRET_KEY environment variable. This secret becomes the Bearer token that clients must include in their HTTP Authorization headers.

Supported configuration methods:

• CLI Flags: --auth-enable, --secret-key
• Environment Variables: REMOTE_AUTH_ENABLE, REMOTE_SECRET_KEY

Implementation Details

The StaticTokenVerifier validates incoming requests by checking the Authorization: Bearer <token> header against the configured static token. The token map includes default scopes of ["read", "write"] and a fixed client_id of "airflow-api-client".

If the installed FastMCP version lacks StaticTokenVerifier (indicated by HAS_AUTH_SUPPORT = False), the server aborts with an error: "Bearer token authentication requested but not supported" (lines 48-53).

Running Without Authentication

The streamable-http transport mode can operate without authentication for development or trusted network environments.

Open Access Mode

By default, if you omit --auth-enable and REMOTE_AUTH_ENABLE, or explicitly set them to false, the server starts without an auth object. In this mode, any HTTP request to the streamable-http endpoint is accepted without token validation.

Security Warnings

When running without authentication, the server logs a warning message: "streamable-http mode without authentication enabled!" (lines 57-60 in src/mcp_airflow_api/mcp_main.py). This serves as a reminder that the endpoint is exposed without access controls.

Distinguishing Transport Auth from Airflow API Auth

It is important to distinguish between the streamable-http transport authentication and the internal Airflow API authentication.

The JWT token logic found in src/mcp_airflow_api/functions.py handles authentication for Airflow API v2 communication (internal API calls to your Airflow instance). This is separate from the transport-level authentication of the streamable-http server, which uses the Bearer token mechanism described above.

Practical Configuration Examples

Example 1: Bearer Token Authentication

Run the server with static token authentication enabled:

AIRFLOW_API_BASE_URL=http://localhost:8080/api \
REMOTE_AUTH_ENABLE=true \
REMOTE_SECRET_KEY=mySuperSecret \
python -m mcp_airflow_api.mcp_main \
  --type streamable-http \
  --host 127.0.0.1 \
  --port 8000 \
  --auth-enable

Clients must include the header: Authorization: Bearer mySuperSecret.

Example 2: Open Access Mode

Run the server without authentication for development:

AIRFLOW_API_BASE_URL=http://localhost:8080/api \
python -m mcp_airflow_api.mcp_main \
  --type streamable-http \
  --host 127.0.0.1 \
  --port 8000

Summary

• Bearer token authentication is the primary authentication mechanism supported for streamable-http transport mode, implemented via FastMCP's StaticTokenVerifier in src/mcp_airflow_api/mcp_main.py.
• Configuration requires --auth-enable or REMOTE_AUTH_ENABLE=true plus a secret key provided via --secret-key or REMOTE_SECRET_KEY.
• No authentication mode allows open access when auth flags are omitted, though a warning is logged.
• FastMCP dependency determines availability; if StaticTokenVerifier is missing, the server aborts when auth is requested.
• Airflow API JWT auth in functions.py is unrelated to transport-level streamable-http authentication.

Frequently Asked Questions

What authentication mechanisms are supported for streamable-http transport mode?

The streamable-http transport mode supports optional Bearer token authentication using a static token verifier, or can run without any authentication. It does not support OAuth, JWT, or other dynamic authentication methods for the transport layer itself.

How do I enable bearer token authentication in mcp-airflow-api?

Enable authentication by setting the --auth-enable CLI flag or REMOTE_AUTH_ENABLE=true environment variable, and provide a secret key via --secret-key or REMOTE_SECRET_KEY. The server then validates Authorization: Bearer <token> headers against this static secret using FastMCP's StaticTokenVerifier.

What happens if I run streamable-http without authentication?

If you omit the authentication flags, the server starts in open access mode and accepts all requests without token validation. A warning message is logged: "streamable-http mode without authentication enabled!" This mode is suitable only for trusted network environments or development.

Is JWT authentication used for the streamable-http transport?

No. The JWT token logic found in src/mcp_airflow_api/functions.py is used exclusively for authenticating with the Airflow API v2 backend. The streamable-http transport authentication is handled separately via Bearer tokens and StaticTokenVerifier in mcp_main.py.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}