# How to Migrate from API v1 to v2 When Upgrading Airflow

> Migrate from Airflow API v1 to v2 easily. Simply set environment variables AIRFLOW_API_VERSION to v2 and AIRFLOW_API_BASE_URL to your Airflow 3.x instance. Restart MCP server for JWT and asset tools.

- Repository: [JungJungIn/mcp-airflow-api](https://github.com/call518/mcp-airflow-api)
- Tags: migration-guide
- Published: 2026-02-26

---

**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`](https://github.com/call518/mcp-airflow-api/blob/main/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:

```bash
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`](https://github.com/call518/mcp-airflow-api/blob/main/src/mcp_airflow_api/mcp_main.py) dynamically loads the appropriate tool set based on the detected API version (lines 41-50):

```python
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`](https://github.com/call518/mcp-airflow-api/blob/main/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**:

```python

# 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:

```python

# 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`](https://github.com/call518/mcp-airflow-api/blob/main/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`](https://github.com/call518/mcp-airflow-api/blob/main/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`](https://github.com/call518/mcp-airflow-api/blob/main/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.