Summary

Extends the MCP server's plugin mode to work with Airflow 2.x, matching the existing Airflow 3 plugin support. The MCP server can now run embedded in an AF2 webserver process with endpoints at /mcp/v1/, rather than only as a standalone sidecar.

Design rationale

Why a Flask blueprint? AF2's webserver is Flask/WSGI, not FastAPI/ASGI like AF3. Plugins register via flask_blueprints instead of fastapi_apps. The blueprint lives in the same plugin.py as the AF3 integration and only activates when FastAPI isn't importable.

Why an ASGI bridge? FastMCP is ASGI-native. Rather than reimplement the MCP Streamable HTTP protocol in Flask, the plugin runs one asyncio event loop in a daemon thread and submits each Flask request to it via run_coroutine_threadsafe. The FastMCP lifespan is started once on the shared loop so the task group stays initialized.

Why lazy init (not at plugin load)? Gunicorn forks worker processes and threads don't survive the fork. The event loop + lifespan start on the first request in each worker, guarded by a threading lock.

Why a module-level dict for auth (not ContextVars)? ContextVars don't propagate across the thread boundary from the gunicorn worker into the background asyncio loop. A plain dict works because gunicorn sync workers handle one request at a time per worker. Both bearer tokens (Astro) and basic auth (local) are captured from the incoming request and read by the adapter when it makes internal calls.

Why lazy _get_plugin_url()? On Astro, webserver.base_url is populated by the runtime after plugin import. The deployment path prefix (e.g. /d99lgbz8) is required for internal calls to localhost, so the URL is constructed on first request rather than at module load.

Why exempt the blueprint from CSRF? MCP clients use bearer/basic auth, not session cookies. Flask-WTF's CSRF check would reject every POST otherwise. Handled in @bp.record_once.

Usage

Install into an Airflow 2.x environment using the plugin-v2 extra. The plugin auto-registers. Connect from an MCP client at https://<airflow>/mcp/v1/ with an Authorization header matching the webserver's auth backend (basic auth locally, bearer token on Astro).

Tested

• Local Docker (Airflow 2.11.0, basic auth): get_airflow_version and list_dags returned 75 DAGs with auth correctly forwarded
• Astro stage (Airflow 2.11.2, deployment JWT): 20/20 requests succeeded, tool calls return real data (example_astronauts)
• Unit tests: 437 pass (10 plugin tests, up from 7)

Gotchas

• On Astro dev deployments, the plugin is loaded per-worker. During rolling restarts there's a brief window where some requests may hit workers that haven't loaded the plugin yet; they'll see 404s until the rollout settles.
• The FastMCP lifespan warms on first request, which adds ~100ms of latency to the first MCP call per worker process.