How to Migrate from API v1 to v2 When Upgrading Airflow

Set the AIRFLOW_API_VERSION environment variable to v2, ensure your AIRFLOW_API_BASE_URL points to your Airflow 3.x instance, and restart the MCP server to automatically enable JWT authentication and asset management tools.

When upgrading from Airflow 2.x to 3.x, you must migrate from API v1 to v2 to access new data-aware scheduling features and modern authentication flows. The mcp-airflow-api project abstracts these version differences behind a unified MCP tool interface, allowing you to upgrade your Airflow deployment without rewriting client logic. This guide shows you exactly how to migrate from API v1 to v2 when upgrading Airflow while preserving your existing tool configurations.

Understanding Version-Aware Request Handling

All HTTP calls in the mcp-airflow-api project are funneled through the airflow_request function in src/mcp_airflow_api/functions.py. This function automatically adapts to your target API version through two key mechanisms.

URL Construction and Version Detection

The construct_api_url helper (lines 28-35) builds endpoints by reading the AIRFLOW_API_VERSION environment variable. When set to v2, all requests target the /api/v2/ path prefix instead of /api/v1/.

Authentication Strategy

The request handler implements version-specific authentication logic (lines 55-68):

• v1 (Airflow 2.x): Uses Basic Auth with AIRFLOW_API_USERNAME and AIRFLOW_API_PASSWORD.
• v2 (Airflow 3.x): Automatically obtains a JWT token via get_jwt_token (line 61) and caches it. If token acquisition fails, it gracefully falls back to Basic Auth.

The actual request dispatch occurs in lines 70-78, where the prepared headers and authentication are injected into the HTTP call.

Configuring Environment Variables for v2 Migration

Migrating from API v1 to v2 requires updating your environment configuration. The following variables control the version switch:

Variable	Purpose	v2 Configuration
AIRFLOW_API_VERSION	API version selector – the only required change	v2
AIRFLOW_API_BASE_URL	Base URL of the Airflow API	http://localhost:8080/api
AIRFLOW_API_USERNAME	Username for Basic Auth and JWT acquisition	your Airflow user
AIRFLOW_API_PASSWORD	Password for Basic Auth and JWT acquisition	your Airflow password
AIRFLOW_JWT_TOKEN_TTL	(Optional) Seconds before cached JWT expires	default ~23 hours

Set these variables before starting the server:

export AIRFLOW_API_VERSION=v2
export AIRFLOW_API_BASE_URL=http://my-airflow.example.com/api
export AIRFLOW_API_USERNAME=admin
export AIRFLOW_API_PASSWORD=very_secret

After restarting the MCP server, get_api_version() (functions.py, line 61) reads the environment variable and all subsequent calls use the v2 endpoint.

Registering v2 Tools and Asset Management

The tool registration logic in src/mcp_airflow_api/mcp_main.py dynamically loads the appropriate tool set based on the detected API version (lines 41-50):

api_version = get_api_version()

if api_version == "v1":
    from mcp_airflow_api.tools import v1_tools
    v1_tools.register_tools(mcp_instance)
elif api_version == "v2":
    from mcp_airflow_api.tools import v2_tools
    v2_tools.register_tools(mcp_instance)

Both versions share 43 common tools defined in src/mcp_airflow_api/tools/common_tools.py. The v2 package adds two asset-management tools that enable data-aware scheduling:

1. list_assets (v2_tools.py, lines 26-60): Returns a paginated list of data assets registered in Airflow.
2. list_asset_events (v2_tools.py, lines 63-99): Retrieves lineage events for a given asset.

These tools are only available when api_version is set to v2 and connect to Airflow 3.x's new data-aware scheduling features.

Verifying Your Migration

After configuration changes, follow these steps to confirm successful migration to API v2:

1. Check server initialization logs for the message Initializing MCP server for Airflow API v2 (mcp_main.py, line 36).

2. Verify tool availability by listing registered tools. You should see 45 total tools (43 common + 2 asset tools) instead of 43.

3. Test a v2-specific endpoint:

# This call only works against Airflow 3.x v2 API

await list_assets(limit=10, uri_pattern="s3://my-bucket/*")

# Expected response includes api_version field

{
  "assets": [...],
  "total_entries": 42,
  "api_version": "v2",
  "feature": "assets"
}

4. Confirm authentication mode: Check that JWT tokens are being cached (visible in debug logs) or that requests include Authorization: Bearer headers.

If you still see v1 registration messages or missing asset tools, verify that AIRFLOW_API_VERSION is exported in the same shell that launches the server.

Handling Hybrid Authentication Environments

If your Airflow 3.x deployment does not expose the JWT endpoint (for example, during a partial upgrade), the mcp-airflow-api client automatically falls back to Basic Auth. No code changes are required—simply ensure AIRFLOW_API_USERNAME and AIRFLOW_API_PASSWORD remain valid:

# The request will use Basic Auth if JWT acquisition fails

# This works against both v1 and v2 endpoints

await get_dag(dag_id="example_dag")

This fallback mechanism ensures continuous operation during gradual migrations or when running against Airflow instances with authentication restrictions.

Summary

Migrating from Airflow API v1 to v2 requires minimal configuration changes when using the mcp-airflow-api project:

• Set AIRFLOW_API_VERSION=v2 to switch endpoint prefixes and authentication modes automatically.
• Update AIRFLOW_API_BASE_URL to point to your Airflow 3.x instance.
• Leverage JWT authentication handled transparently by get_jwt_token in functions.py, with automatic Basic Auth fallback.
• Access new asset tools (list_assets, list_asset_events) available only in v2 for data-aware scheduling.
• Verify migration through server logs and tool counts (45 tools in v2 vs 43 in v1).

Frequently Asked Questions

What is the minimum Airflow version required for API v2?

Airflow API v2 requires Airflow 3.0 or higher. The v2 endpoints introduce breaking changes in authentication (JWT tokens) and add asset management capabilities that do not exist in Airflow 2.x. If you attempt to use AIRFLOW_API_VERSION=v2 against an Airflow 2.x instance, requests will fail with 404 errors for the v2 endpoint paths.

Do I need to rewrite my existing tool calls when migrating to v2?

No, existing tool calls require no code changes. The 43 common tools in common_tools.py maintain identical function signatures across both versions. Only the underlying HTTP transport changes—switching from Basic Auth to JWT tokens and updating endpoint prefixes from /api/v1/ to /api/v2/. Your existing get_dag, trigger_dag_run, and other calls work identically in both versions.

How does the JWT token caching work?

The get_jwt_token function in functions.py (line 61) obtains tokens via the Airflow login endpoint and caches them in memory for the duration specified by AIRFLOW_JWT_TOKEN_TTL (default approximately 23 hours). This prevents repeated authentication requests and reduces load on your Airflow API. If the token expires or the JWT endpoint becomes unavailable, the system automatically falls back to Basic Auth using your configured username and password without interrupting service.

What are the asset management tools and when should I use them?

The v2-specific tools list_assets and list_asset_events enable data-aware scheduling workflows unique to Airflow 3.x. Use list_assets (v2_tools.py, lines 26-60) to discover registered data assets like S3 buckets or database tables that trigger DAGs. Use list_asset_events (lines 63-99) to audit lineage events such as asset creation or updates. These tools are essential when migrating to Airflow 3.x's asset-centric scheduling model but are unavailable in Airflow 2.x deployments.

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