# v2-Exclusive Asset Management Tools in mcp-airflow-api: A Complete Guide

> Explore v2-exclusive asset management tools list_assets and list_asset_events in mcp-airflow-api. Learn how they leverage Airflow 3.0 Assets REST API.

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

---

**The `mcp-airflow-api` package provides two v2-exclusive asset management tools—`list_assets` and `list_asset_events`—that expose Airflow 3.0's Assets REST API through the Model Context Protocol (MCP) framework.**

Airflow 3.0 introduced **Assets** (formerly "datasets") as the core building block for data-aware scheduling, replacing the legacy dataset model with a unified asset registry. The `mcp-airflow-api` repository implements v2-exclusive asset management tools that allow MCP clients to query this registry and monitor asset lineage events. These tools are only available when connecting to Airflow 3.x clusters via API v2, providing programmatic access to asset metadata and event history.

## What Are v2-Exclusive Asset Management Tools?

V2-exclusive asset management tools are specialized MCP tools registered only when the server operates in **API v2 mode** (Airflow 3.x). Unlike the common tools shared across API versions, these tools interact with the `/assets` and `/assets/events` endpoints introduced in Airflow 3.0's REST API.

The `mcp-airflow-api` package implements two distinct v2-exclusive asset management tools:

- **`list_assets`**: Retrieves paginated asset registries with optional URI pattern filtering
- **`list_asset_events`**: Queries asset lineage events with filters for specific assets or source DAGs

### list_assets: Retrieving Asset Registries

The `list_assets` tool provides read access to the Airflow asset catalog. Located in [`src/mcp_airflow_api/tools/v2_tools.py`](https://github.com/call518/mcp-airflow-api/blob/main/src/mcp_airflow_api/tools/v2_tools.py) (lines 28-61), this async function constructs paginated queries against the `/assets` endpoint.

**Method signature:**

```python
async def list_assets(
    limit: int = 20, 
    offset: int = 0, 
    uri_pattern: Optional[str] = None
) -> Dict[str, Any]

```

**Implementation workflow:**
1. Builds query parameters from `limit`, `offset`, and optional `uri_pattern` arguments
2. Calls `airflow_request_v2("GET", f"/assets?{query_string}")` to execute the authenticated request
3. Returns a dictionary containing the asset list, total count, pagination metadata, and a metadata block identifying the API version (`api_version: "v2"`) and feature (`feature: "assets"`)

### list_asset_events: Tracking Asset Lineage

The `list_asset_events` tool monitors the event stream that tracks asset creation and updates. Also defined in [`src/mcp_airflow_api/tools/v2_tools.py`](https://github.com/call518/mcp-airflow-api/blob/main/src/mcp_airflow_api/tools/v2_tools.py) (lines 63-101), this tool queries the `/assets/events` endpoint to retrieve lineage metadata.

**Method signature:**

```python
async def list_asset_events(
    limit: int = 20, 
    offset: int = 0, 
    asset_uri: Optional[str] = None,
    source_dag_id: Optional[str] = None
) -> Dict[str, Any]

```

**Implementation workflow:**
1. Assembles query parameters including `limit`, `offset`, and optional filters (`asset_uri`, `source_dag_id`)
2. Dispatches `airflow_request_v2("GET", f"/assets/events?{query_string}")` to the Airflow 3.x REST API
3. Wraps the response with pagination data and metadata flags (`api_version: "v2"`, `feature: "asset_events"`), enabling clients to identify the source API version

## How v2-Exclusive Asset Management Tools Work

These tools leverage Airflow 3.0's redesigned REST API architecture, specifically the v2 endpoints that replaced the experimental dataset API. The implementation relies on version-specific request handlers and conditional tool registration.

### API v2 Request Handling

Both asset management tools utilize the `airflow_request_v2` function defined in [`src/mcp_airflow_api/functions.py`](https://github.com/call518/mcp-airflow-api/blob/main/src/mcp_airflow_api/functions.py). This wrapper handles authentication, base URL resolution, and HTTP client management specifically for Airflow 3.x deployments.

When the MCP server initializes in v2 mode, the registration logic in [`v2_tools.py`](https://github.com/call518/mcp-airflow-api/blob/main/v2_tools.py) overwrites the common tools' request handler:

```python

# During v2 tool registration

common_tools.airflow_request = airflow_request_v2

```

This ensures that all tools—both common and v2-exclusive—use the correct endpoint prefix and authentication scheme for the target Airflow version.

### Response Structure and Metadata

V2-exclusive asset management tools return standardized response dictionaries that include both the raw API data and MCP-specific metadata. This structure enables clients to handle pagination and identify API capabilities:

**Response schema:**
- `assets` or `asset_events`: List of retrieved items
- `total`: Total count of available records
- `limit`/`offset`: Current pagination parameters
- `metadata`: Dictionary containing `api_version` ("v2") and `feature` identifier

This metadata block is particularly valuable for AI agents using the MCP framework, as it allows them to confirm they are interacting with Airflow 3.x asset features rather than legacy dataset implementations.

## Working with v2-Exclusive Asset Management Tools: Code Examples

The following examples demonstrate how to invoke these tools within an MCP client context. These assume the server is running in API v2 mode against an Airflow 3.x cluster.

**Listing assets with URI pattern filtering:**

```python

# Retrieve S3-based assets with pagination

assets_response = await mcp.tool("list_assets")(
    limit=10, 
    uri_pattern="s3://my-bucket/"
)

print(f"Found {assets_response['total']} total assets")
for asset in assets_response["assets"]:
    print(f"  - {asset['uri']} (ID: {asset['id']})")

```

**Querying asset events for lineage tracking:**

```python

# Get recent events for a specific asset

events_response = await mcp.tool("list_asset_events")(
    asset_uri="s3://my-bucket/table1",
    limit=5
)

for event in events_response["asset_events"]:
    print(f"{event['event_type']} event from DAG {event['source_dag_id']} "
          f"at {event['timestamp']}")

```

**Paginating through large asset catalogs:**

```python

# Iterate through all assets in batches

offset = 0
batch_size = 50
all_assets = []

while True:
    batch = await mcp.tool("list_assets")(limit=batch_size, offset=offset)
    all_assets.extend(batch["assets"])
    
    if offset + batch_size >= batch["total"]:
        break
    offset += batch_size

```

## Source Code Architecture

The v2-exclusive asset management tools are implemented across three primary files in the `mcp-airflow-api` repository:

| File | Description |
|------|-------------|
| **[`src/mcp_airflow_api/tools/v2_tools.py`](https://github.com/call518/mcp-airflow-api/blob/main/src/mcp_airflow_api/tools/v2_tools.py)** | Contains the tool definitions for `list_assets` (lines 28-61) and `list_asset_events` (lines 63-101), including parameter validation and response formatting. |
| **[`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)** | Houses the 43 shared tools available across API versions; the v2 asset tools extend this set and override the request handler during registration. |
| **[`src/mcp_airflow_api/functions.py`](https://github.com/call518/mcp-airflow-api/blob/main/src/mcp_airflow_api/functions.py)** | Defines `airflow_request_v2`, the HTTP wrapper used by asset management tools to communicate with Airflow 3.x REST endpoints. |

During server initialization, the v2 tool registration logic conditionally exposes these asset management capabilities only when the configuration specifies API version 2, ensuring backward compatibility with Airflow 2.x deployments.

## Summary

- **V2-exclusive asset management tools** (`list_assets` and `list_asset_events`) are only available when connecting to Airflow 3.x clusters via API v2.
- **`list_assets`** queries the `/assets` endpoint to retrieve paginated asset registries with optional URI pattern filtering.
- **`list_asset_events`** accesses the `/assets/events` endpoint to track lineage events (creation/update) filtered by asset URI or source DAG.
- Both tools use **`airflow_request_v2`** for HTTP handling and return standardized responses with metadata flags identifying the API version.
- The implementation resides in **[`src/mcp_airflow_api/tools/v2_tools.py`](https://github.com/call518/mcp-airflow-api/blob/main/src/mcp_airflow_api/tools/v2_tools.py)**, with registration logic ensuring these tools only appear in v2 mode.

## Frequently Asked Questions

### What is the difference between v2-exclusive asset management tools and common tools in mcp-airflow-api?

Common tools 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) are available across all API versions and provide general Airflow operations like triggering DAGs or checking task status. V2-exclusive asset management tools specifically target Airflow 3.0's Assets REST API and are only registered when the server runs in API v2 mode. These tools expose endpoints like `/assets` and `/assets/events` that do not exist in Airflow 2.x, making them incompatible with earlier versions.

### How do I filter assets by URI pattern using the list_assets tool?

The `list_assets` tool accepts an optional `uri_pattern` parameter that performs substring matching against asset URIs. Pass a string value to filter results, such as `uri_pattern="s3://my-bucket/"` to retrieve only S3 assets from a specific bucket. The tool constructs a query string from this parameter and sends it to the Airflow `/assets` endpoint, returning only matching assets in the paginated response.

### Can I track which DAG created or updated a specific asset using these tools?

Yes, the `list_asset_events` tool provides lineage tracking by querying the `/assets/events` endpoint. Use the `asset_uri` parameter to specify the target asset, and the response includes `source_dag_id` fields indicating which DAG triggered each creation or update event. You can also filter by `source_dag_id` directly to see all assets modified by a specific DAG, enabling complete bidirectional lineage tracing between DAGs and assets.

### Why are these asset management tools only available in API v2 mode?

These tools depend on Airflow 3.0's redesigned REST API, which introduced the `/assets` and `/assets/events` endpoints to replace the experimental dataset API from Airflow 2.x. The `mcp-airflow-api` server conditionally registers these tools only when configured for API v2, ensuring that clients connecting to Airflow 2.x clusters do not attempt to call non-existent endpoints. This version-gated registration prevents runtime errors while exposing Airflow 3.0's advanced asset-aware scheduling capabilities to compatible deployments.