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

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 (lines 28-61), this async function constructs paginated queries against the /assets endpoint.

Method signature:

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 (lines 63-101), this tool queries the /assets/events endpoint to retrieve lineage metadata.

Method signature:

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. 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 overwrites the common tools' request handler:

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

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

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

# 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	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	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	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, 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 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.

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