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

> Explore limitations of mcp-airflow-api configuration query tools. Discover restrictions including Airflow 2.x endpoints, read-only access, and basic search.

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

---

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

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

```python

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

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