run_job MCP tool: support row-level execution via configRowIds

[beckavac]

Problem

The run_job MCP tool only accepts component_id and configuration_id, with no way to target specific rows of a row-based configuration.

For row-based extractors (e.g. keboola.ex-db-mysql), this means you can only run the entire configuration. Real-world configs often have hundreds of rows — for example, a single MySQL extractor config in our project has 303 rows. Running the full config for a targeted reload of one source table is not viable.

The underlying Keboola Job Queue API does support this:

POST https://queue.keboola.com/jobs
{
  "component": "keboola.ex-db-mysql",
  "config": "data-pro-crm-tym-90",
  "configRowIds": ["47198"],
  "mode": "run"
}

Current schema

{
  "component_id": "string",
  "configuration_id": "string"
}

Proposal

Add an optional configuration_row_ids: string[] parameter that maps to configRowIds in the Job Queue API.

Impact

Without this, automated workflows around row-based components (targeted backfills, single-table reloads, debugging individual rows) have to bypass the MCP layer and call the Queue API directly with a raw token.

[padak]

Thanks for the detailed report — you're right that the MCP run_job tool only exposes component_id / configuration_id today. That schema is owned by keboola/keboola-mcp-server, so the actual fix has to land there.

In the meantime, the kbagent CLI already hits the Queue API with configRowIds natively — no raw token / curl needed:

kbagent job run \
  --project <alias> \
  --component-id keboola.ex-db-mysql \
  --config-id data-pro-crm-tym-90 \
  --row-id 47198 \
  --wait

--row-id is repeatable for multi-row runs; omitting it runs the full config. The CLI maps it 1:1 to the configRowIds array in the POST body you pasted (see src/keboola_agent_cli/client.py:2041, covered by tests/test_client.py:2566). Available since v0.7.x; current release is v0.27.0.

That should unblock the targeted-backfill / single-table-reload workflows immediately. Happy to file the upstream issue against keboola-mcp-server for the MCP-level fix if you'd like.

[beckavac]

Thanks for the pointer — kbagent job run --row-id is exactly what I needed and I missed it in the CLI docs. Just verified kbagent job run --help shows --row-id clearly. Used run_job MCP tool by reflex without checking the CLI surface.

For the workflow I had (sequential per-row reload with patch → run → wait → revert), kbagent job run --project <alias> --component-id <c> --config-id <cfg> --row-id <id> --wait covers it cleanly without bypassing kbagent.

Yes please, file the upstream issue against keboola/keboola-mcp-server to add configuration_row_ids to the MCP run_job tool schema — that's where the real gap is. Happy for this issue (#243) to be closed once the upstream is opened (or kept as a tracker pointing there, your call).

Also updated my local notes / feedback memory so I default to kbagent job run --row-id for row-level execution next time.

[padak]

Quick correction on my earlier comment — I dug deeper and the MCP-side gap I described is no longer accurate.

The configuration_row_ids parameter was added to run_job upstream on 2026-03-25 (commit 35ce8afc, ticket AI-2889) and renamed to its current name on 2026-04-01. It shipped in keboola-mcp-server v1.55.0 (released 2026-04-17) and is present in the latest v1.59.1, which is what kbagent v0.27.0 already pulls via uvx. Confirmed at the tag: src/keboola_mcp_server/tools/jobs.py lines 420 / 427 / 444 in v1.59.1. (The GitHub Releases page still showing v1.57.1 is just the manual "Create release" step in the keboola/mcp-server repo lagging behind the actual git tags / PyPI publish.)

So the MCP path should already work today. From kbagent it would be:

kbagent tool call run_job --project <alias> \
  --input '{"component_id":"keboola.ex-db-mysql","configuration_id":"data-pro-crm-tym-90","configuration_row_ids":["47198"]}'

(Parameter name is configuration_row_ids, not configRowIds — the MCP layer maps it to the wire format internally.)

Could you share a Claude session / transcript from when you originally hit this? Specifically helpful would be:

• which MCP client you were using (Claude Desktop, Claude Code, Cursor, custom),
• the keboola-mcp-server version that client had picked up (cached schemas can lag for a while, and some hosted MCP setups pin older versions),
• the exact tool call payload that got rejected or silently ignored.

That would let us figure out whether it was a stale schema cache, an older pinned MCP server, or how the LLM was framing the call. Glad the native CLI workaround unblocked you in the meantime.

[beckavac]

Got the info you asked for — interesting find:

• MCP client: Claude Code (Anthropic CLI agent harness, latest)
• kbagent: v0.27.0
• keboola-mcp-server (locally installed): v1.49.0 ← older than v1.55.0 where configuration_row_ids was added

Verified by trying the call you suggested:

$ kbagent --json tool call run_job --project <p> --input '{"component_id":"keboola.snowflake-transformation","configuration_id":"01kc9g4wsq1rssfhzhwnjj364c","configuration_row_ids":["nonexistent"]}'

Found 1 validation error(s) for call[run_job]
errors:
- field: configuration_row_ids
  message: Unexpected keyword argument

So my local MCP server schema genuinely doesn't expose the field — confirms what kbagent --json tool list showed me at session start (just component_id + configuration_id).

Why it's stale: I installed it once per the kbagent skill setup:

uv tool install --prerelease=allow keboola-mcp-server

uv tool install pins the version at install time and doesn't auto-update. So whoever installs once gets whatever version was on PyPI that day, then drifts behind without realizing.

Suggestions (none needs to land in this issue, just FYI):

1. The kbagent skill's setup section could mention upgrading: uv tool upgrade keboola-mcp-server (or uv tool install --reinstall ...).
2. Or kbagent could opportunistically warn / log the MCP server version somewhere (e.g., in kbagent doctor output) so users see when they're behind.
3. The kbagent context output already shows kbagent v0.27.0 at the top — could also surface the MCP server version next to it.

Just upgraded mine (uv tool upgrade keboola-mcp-server) and will verify the schema shows configuration_row_ids — will close the loop. Native MCP path FTW.

[beckavac]

Closing the loop:

$ uv tool upgrade keboola-mcp-server --prerelease=allow
# v1.49.0 → v1.59.1

$ kbagent --json tool list | jq '.data.tools[] | select(.name=="run_job") | .inputSchema.properties | keys'
[
  "component_id",
  "configuration_id",
  "configuration_row_ids"  ← present!
]

So it really was just stale local install. MCP path now works as you described, no need for the CLI workaround for this case.

For the upstream issue you offered earlier — yes please, but it's now narrower scope: the actual gap was that uv tool install doesn't auto-update, and there's no signal in kbagent that the MCP server is behind. Worth a small UX nudge in kbagent doctor or the setup docs.