How to Configure Bearer Token Authentication for Production Deployments in MCP Airflow API

Enable Bearer token authentication by setting the transport type to streamable-http, activating the auth flag with --auth-enable or REMOTE_AUTH_ENABLE=true, and providing a secret key via --secret-key or REMOTE_SECRET_KEY to initialize the static token verifier.

The MCP Airflow API supports secure production deployments through JWT Bearer token authentication, which restricts access to the HTTP transport layer. When deploying call518/mcp-airflow-api in production environments, configuring this authentication mechanism ensures that only authorized Airflow workers can communicate with the MCP server endpoints.

Prerequisites for Bearer Token Authentication

Transport Mode Requirements

Bearer token authentication is exclusively available when running the server in streamable-http mode. The transport type must be explicitly set using either the CLI argument --type streamable-http or the environment variable FASTMCP_TYPE=streamable-http. According to the source code in src/mcp_airflow_api/mcp_main.py, attempting to enable authentication with other transport modes triggers a warning at lines 62-64 and bypasses the auth provider initialization.

FastMCP Version Compatibility

The authentication feature depends on the StaticTokenVerifier class from the underlying fastmcp library. The code defines a HAS_AUTH_SUPPORT flag at the module level in src/mcp_airflow_api/mcp_main.py. If your fastmcp version lacks this class, the server aborts during startup with an error at lines 349-352, preventing deployment with authentication enabled.

Configuration Methods for Production

Environment Variable Configuration

For containerized production deployments, use environment variables to configure authentication without exposing secrets in process lists. Set the following variables before starting the server:

export FASTMCP_TYPE=streamable-http
export FASTMCP_HOST=0.0.0.0
export FASTMCP_PORT=8080
export REMOTE_AUTH_ENABLE=true
export REMOTE_SECRET_KEY=$(cat /run/secrets/mcp_secret)  # Load from secrets manager

python -m mcp_airflow_api

The REMOTE_SECRET_KEY variable maps to the --secret-key CLI argument and is validated at lines 53-56 in src/mcp_airflow_api/mcp_main.py. If the secret is missing when auth is enabled, the server exits immediately with a configuration error.

Command-Line Interface Configuration

For development or systemd service definitions, pass authentication parameters directly:

python -m mcp_airflow_api \
    --type streamable-http \
    --host 127.0.0.1 \
    --port 8000 \
    --auth-enable \
    --secret-key "my-production-secret-key"

The argument parser collects these options at lines 89-108 in src/mcp_airflow_api/mcp_main.py, ensuring that --auth-enable and --secret-key are processed together before server initialization.

Implementing the Static Token Verifier

When authentication is enabled, the server initializes the StaticTokenVerifier through the _build_static_token_auth() function. This occurs at lines 66-72 in src/mcp_airflow_api/mcp_main.py:

if auth_enable:
    try:
        mcp.auth = _build_static_token_auth(secret_key)  # Initializes StaticTokenVerifier

    except Exception as e:
        logger.error(f"ERROR: Failed to initialize StaticTokenVerifier: {e}")
        return

The verifier validates incoming requests by checking the Authorization: Bearer <token> header against the configured secret key. If authentication is disabled, the server logs a warning at lines 58-61 indicating that unauthenticated requests will be accepted.

Generating Client JWT Tokens

Clients must present valid JWTs signed with the same secret key configured on the server. Generate tokens using the HS256 algorithm:

import jwt
import datetime

secret = "my-production-secret-key"  # Must match REMOTE_SECRET_KEY

payload = {
    "sub": "airflow-worker",
    "iat": datetime.datetime.utcnow(),
    "exp": datetime.datetime.utcnow() + datetime.timedelta(hours=2),
}

token = jwt.encode(payload, secret, algorithm="HS256")
print(f"Authorization: Bearer {token}")

The client includes this token in the Authorization header. The server validates this against the static token verifier configured in src/mcp_airflow_api/mcp_main.py.

Production Security Checklist

Before deploying to production, verify these critical security measures:

• Upgrade fastmcp: Confirm your environment includes the StaticTokenVerifier class. The server checks HAS_AUTH_SUPPORT at startup and aborts if authentication is requested but unsupported.
• Secret Management: Store REMOTE_SECRET_KEY in a dedicated secrets manager (HashiCorp Vault, AWS Secrets Manager, or Kubernetes secrets) and inject it at runtime. Never commit secrets to version control or expose them in process lists.
• TLS Termination: Deploy the streamable-http server behind a reverse proxy (NGINX, Traefik, or Envoy) that handles TLS termination, ensuring Bearer tokens never traverse the network in plaintext.
• Token Rotation: Implement short-lived JWTs with expiration claims (exp) and rotate the signing secret periodically by updating REMOTE_SECRET_KEY and restarting the server.

Summary

Configuring Bearer token authentication for the MCP Airflow API requires running the server in streamable-http mode with the --auth-enable flag and a configured --secret-key. The authentication provider initializes in src/mcp_airflow_api/mcp_main.py using the StaticTokenVerifier class from the fastmcp library, validating JWTs presented in the Authorization: Bearer header. For production security, store secrets in dedicated managers, terminate TLS at a reverse proxy, and ensure your fastmcp version supports the authentication features.

Frequently Asked Questions

Is Bearer token authentication supported in SSE mode?

No, Bearer token authentication is only supported when using the streamable-http transport type. If you enable authentication with other transports, the server logs a warning at lines 62-64 in src/mcp_airflow_api/mcp_main.py and continues without authentication enabled.

What happens if I enable auth without providing a secret key?

The server exits immediately with a configuration error. The validation logic at lines 53-56 in src/mcp_airflow_api/mcp_main.py checks for the presence of REMOTE_SECRET_KEY or --secret-key when auth_enable is true, and terminates the process if the secret is missing.

How do I verify my fastmcp version supports authentication?

Check that your installed fastmcp library includes the StaticTokenVerifier class. The MCP Airflow API defines HAS_AUTH_SUPPORT at the module level in src/mcp_airflow_api/mcp_main.py and aborts at lines 349-352 if you attempt to enable authentication without this class present.

Can I rotate the secret key without downtime?

No, rotating the secret key requires a server restart. The REMOTE_SECRET_KEY is read once during initialization in src/mcp_airflow_api/mcp_main.py when building the static token verifier. To rotate keys safely, deploy a new instance with the updated secret, redirect traffic, then decommission the old instance.

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