Limitations of the Configuration Query Tools in mcp-airflow-api

The configuration query tools in the mcp-airflow-api repository are restricted to Airflow 2.x endpoints, require expose_config = True in the webserver configuration, provide read-only access without pagination or caching, and offer only basic substring search without regex support.

The call518/mcp-airflow-api repository provides Model Context Protocol (MCP) tools that expose Apache Airflow's configuration through REST API endpoints. While these tools offer convenient access to configuration data, understanding the limitations of the configuration query tools is essential for production deployments, as constraints stem from Airflow's API design, security settings, and implementation choices in the source code.

Overview of the Configuration Query Tools

The repository implements four primary configuration query tools in src/mcp_airflow_api/tools/common_tools.py:

• get_config (lines 589‑595): Returns the complete configuration payload
• list_config_sections (lines 596‑614): Summarizes each section with option counts and samples
• get_config_section(section_name) (lines 622‑639): Retrieves all options for a specific section
• search_config_options(search_term) (lines 645‑669): Performs case‑insensitive substring matching on option names and values

These tools rely on the airflow_request helper in src/mcp_airflow_api/functions.py (lines 28‑52) to handle URL construction, authentication via AIRFLOW_API_USERNAME and AIRFLOW_API_PASSWORD, and API version selection.

API Version and Endpoint Restrictions

A critical limitation of the configuration query tools is their dependency on the Airflow 2.x REST API. The /config endpoint exists only in the v1 API namespace.

In src/mcp_airflow_api/functions.py (lines 28‑44), the airflow_request function constructs URLs based on the AIRFLOW_API_VERSION environment variable. If this variable points to Airflow 3.x (v2 API), the configuration endpoint is unavailable, causing the tools to return errors such as {"error": "Configuration access denied: …"}.

This version lock-in means organizations running Airflow 3.x cannot use these tools to query configuration without enabling legacy API endpoints, if available.

Security Configuration Requirements

Even when the correct API version is available, the tools require specific Airflow webserver settings. All four configuration tools wrap their requests in try/except blocks that explicitly check for access restrictions.

If the Airflow webserver configuration (airflow.cfg) sets expose_config = False in the [webserver] section, the API refuses to disclose configuration data. The tools catch these failures and return a standardized error object:

{
  "error": "Configuration access denied: 403 Client Error: Forbidden for url: …",
  "note": "This requires 'expose_config = True' in airflow.cfg [webserver] section"
}

This security gate means the tools cannot function in hardened environments where configuration exposure is intentionally restricted.

Functional Constraints and Data Handling

Beyond infrastructure requirements, the configuration query tools impose several functional limitations on how data is retrieved and searched.

Read-Only Access

The tools are strictly read-only. In src/mcp_airflow_api/tools/common_tools.py, all configuration tools perform GET requests exclusively. They cannot modify, add, or delete configuration options. Updating Airflow settings requires direct interaction with the Airflow UI or manual editing of airflow.cfg followed by service restarts.

No Pagination for Bulk Retrieval

The get_config tool (lines 589‑595) retrieves the entire configuration payload in a single request. Unlike other Airflow API endpoints that support pagination parameters, the configuration endpoint returns all sections and options simultaneously. For large Airflow deployments with extensive custom configurations, this can result in heavy response payloads that increase latency and may hit request size limits.

Basic Search Semantics

The search_config_options tool (lines 645‑669) implements simple case‑insensitive substring matching. It searches for the provided term within option names or their stringified values, but does not support:

• Regular expressions
• Logical operators (AND/OR/NOT)
• Wildcard patterns
• Deep searching within complex JSON configuration values

Results are returned as a flat dictionary of matching sections and options without relevance ranking or highlighting.

Error Handling and Authentication Limitations

The tools provide limited diagnostic information when failures occur, complicating troubleshooting efforts.

Generic Error Responses

When the configuration endpoint is inaccessible, the tools return a generic error object that includes the exception string but omits HTTP status codes or detailed Airflow‑specific diagnostics. This makes it difficult to distinguish between authentication failures, missing endpoints, or the expose_config flag being disabled.

Authentication Constraints

All requests route through airflow_request in src/mcp_airflow_api/functions.py (lines 45‑52), which requires AIRFLOW_API_USERNAME and AIRFLOW_API_PASSWORD environment variables. If the provided credentials lack permission to read the /config endpoint (for example, a service account with limited scope), the tools fail with a 403 error that is collapsed into the generic error response without specific permission details.

No Client-Side Caching

Each call to the configuration tools triggers a fresh HTTP request to the Airflow API. The implementation does not include client‑side caching mechanisms or ETag handling. In environments where configuration changes infrequently, this lack of caching results in unnecessary network overhead and increased latency for repeated queries.

Code Examples and Implementation Details

The following examples demonstrate typical usage and failure modes:

# List all configuration sections with summaries

await mcp.list_config_sections()

# Retrieve all options for the "core" section

await mcp.get_config_section("core")

# Search for configuration related to executors

await mcp.search_config_options("executor")

When expose_config is disabled, the tools return structured error messages:

{
  "error": "Configuration access denied: 403 Client Error: Forbidden for url: …",
  "note": "This requires 'expose_config = True' in airflow.cfg [webserver] section"
}

Summary

The configuration query tools in call518/mcp-airflow-api provide convenient MCP-accessible wrappers around Airflow's REST API, but they carry significant limitations:

• API version dependency: Only compatible with Airflow 2.x (v1 API); Airflow 3.x endpoints are unsupported.
• Security prerequisites: Require expose_config = True in the [webserver] section of airflow.cfg.
• Read-only operations: Cannot modify configuration values; updates require manual intervention.
• Performance constraints: get_config lacks pagination, returning entire payloads in single requests.
• Search limitations: search_config_options supports only case‑insensitive substring matching without regex or logical operators.
• Error opacity: Returns generic error messages that obscure HTTP status codes and specific permission issues.
• No caching: Each request hits the Airflow API directly without client‑side caching or ETag support.

Frequently Asked Questions

Why do the configuration query tools return "Configuration access denied" errors?

The tools require the Airflow webserver to expose configuration data explicitly. If airflow.cfg contains expose_config = False in the [webserver] section, the API returns a 403 Forbidden response. The tools catch this and return a JSON error object noting that expose_config = True is required, as implemented in the exception handlers in src/mcp_airflow_api/tools/common_tools.py.

Can I use these tools with Airflow 3.x?

No. The configuration query tools depend on the /config endpoint, which exists only in the Airflow 2.x REST API (v1). The airflow_request helper in src/mcp_airflow_api/functions.py constructs URLs based on the AIRFLOW_API_VERSION environment variable. When targeting Airflow 3.x (v2 API), the configuration endpoint is unavailable, causing the tools to fail with access denied errors.

Is it possible to modify Airflow configuration using these MCP tools?

No. All configuration query tools in src/mcp_airflow_api/tools/common_tools.py perform read-only GET requests. They can retrieve configuration sections, list options, and search values, but they cannot create, update, or delete configuration entries. Modifying Airflow settings requires using the Airflow web UI or editing the airflow.cfg file directly and restarting the service.

Why does the get_config tool sometimes return large or slow responses?

The get_config tool (lines 589‑595 in src/mcp_airflow_api/tools/common_tools.py) retrieves the entire Airflow configuration in a single API call without pagination. Unlike other Airflow REST endpoints that support limit and offset parameters, the configuration endpoint returns all sections and options simultaneously. For large deployments with extensive custom configurations, this results in heavy payloads that increase network latency and may approach request size limits.

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