kestra-io / kestra-io/mcp-server-python
Kestra 2.0 compatibility: legacy execution action paths and search query parameters break/ignore MCP operations
- Dominant language
- Python
- Stars
- 31
- Forks
- 7
- PR merge metrics
- No merged PRs in 30d
Description
## Summary
The current `kestra-io/mcp-server-python` main branch / image `0.23` is not fully compatible with Kestra 2.0 APIs.
I reproduced this against a self-hosted Kestra OSS **v2.0.0** instance using the server's own `/swagger/kestra.yml` (`info.version: 2.0.0`) and the current MCP server source at commit:
- MCP commit: `14fe3a3344424bb44215b96f00da8e0930ca9a90`
- MCP image: `ghcr.io/kestra-io/mcp-server-python:0.23`
- image digest: `sha256:1fd62028f60914af31e244ddb0086ed5017420313e2c8547ea9c01b8d24dfc1d`
- Kestra edition: OSS
- Kestra version reproduced: `2.0.0`
- tenant: `main`
- `KESTRA_MCP_DISABLED_TOOLS=ee`
Kestra's latest stable release is currently **v2.0.1**, but I have only directly reproduced the issue on v2.0.0.
## Confirmed incompatibilities
### 1. Execution action endpoints moved under `/actions/`
The MCP currently calls legacy paths such as:
```text
POST /executions/{execution_id}/pause
DELETE /executions/{execution_id}/kill
POST /executions/{execution_id}/change-status
POST /executions/{execution_id}/labels
POST /executions/{execution_id}/restart
POST /executions/{execution_id}/state
POST /executions/{execution_id}/resume
POST /executions/{execution_id}/force-run
```
Kestra 2.0 exposes these as:
```text
POST /executions/{executionId}/actions/pause
DELETE /executions/{executionId}/actions/kill
POST /executions/{executionId}/actions/change-status
POST /executions/{executionId}/actions/labels
POST /executions/{executionId}/actions/restart
POST /executions/{executionId}/actions/state
POST /executions/{executionId}/actions/resume
POST /executions/{executionId}/actions/force-run
```
This affects at least `manage_executions`, `restart_execution`, `change_taskrun_state`, `resume_execution`, and `force_run_execution`.
### 2. Kestra 2.0 unified search filters are not used
Several MCP tools still send legacy per-endpoint query params, for example:
```text
/flows/search?q=...&namespace=...
/executions/search?namespace=...&flowId=...&state=...
/logs/{executionId}?minLevel=...&taskId=...&taskRunId=...&attempt=...
/logs/search?q=...&namespace=...&flowId=...&minLevel=...
/namespaces/search?q=...
```
Kestra 2.0 consolidated these into the unified `filters[...]` query model. The legacy params may be silently ignored, which is especially dangerous because calls can appear successful while returning unfiltered data.
For example, execution/log filters need to be expressed in the new model, such as:
```text
filters[namespace][EQUALS]=my.namespace
filters[flowId][EQUALS]=my-flow
filters[state][EQUALS]=FAILED
filters[taskId][EQUALS]=task-id
filters[level][GREATER_THAN_OR_EQUAL_TO]=INFO
```
This is consistent with the Kestra client SDK migration in `kestra-io/client-sdk#253`, which explicitly notes that Kestra 2.0 dropped the old per-endpoint filter query params and that they were silently ignored.
### 3. Backfill endpoint changed
The MCP currently calls:
```text
PUT /triggers
```
for backfill creation.
Kestra 2.0 exposes:
```text
PUT /triggers/backfill/create
```
This affects `backfill_executions`.
### 4. KV list endpoint changed
The MCP `manage_kv_store(action="list")` currently calls:
```text
GET /namespaces/{namespace}/kv
```
In Kestra 2.0 that path is not a GET list endpoint; listing keys is exposed through:
```text
GET /kv
```
with the namespace expressed through the unified filters model.
## What still works
The problem is not that the whole MCP server is unusable. Many core paths still match Kestra 2.0, including the main Flow CRUD paths, flow revisions/dependencies, flow execution creation, execution GET, log retrieval paths, and namespace file CRUD paths.
The stdio MCP itself starts correctly and currently exposes 29 OSS tools when `KESTRA_MCP_DISABLED_TOOLS=ee`.
## Expected behavior
The official MCP server should support the current Kestra 2.0 stable API without requiring a downstream compatibility proxy/patch.
Ideally the public MCP tool schemas remain stable while the HTTP client layer is updated for Kestra 2.0:
1. migrate execution action endpoints to `/actions/...`;
2. translate legacy MCP search arguments to Kestra 2.0 `filters[...]` query parameters;
3. migrate backfill creation to `/triggers/backfill/create`;
4. migrate KV list to `GET /kv` + namespace filter;
5. add integration tests against Kestra 2.x so future API drift is caught.
## Reproduction approach
I compared the fixed MCP image source against the exact OpenAPI document served by the running Kestra v2.0.0 instance rather than a newer online spec. I also built a small compatibility adapter locally and added focused tests for the endpoint and filter translations; those tests pass after rewriting the requests to the v2.0 API shape.
I can provide the compatibility adapter/test cases or open a PR if that would be useful.
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with the HTTP client layer and the named entry points: manage_executions, restart_execution, change_taskrun_state, resume_execution, force_run_execution, backfill_executions, and manage_kv_store. Compare their requests with the Kestra 2.0 OpenAPI document, then add focused integration coverage for action paths, unified filters, backfill creation, and KV listing. Done means all four compatibility areas work against Kestra 2.x while public MCP schemas remain stable.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- api, backend, testing-qa
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 55/100