From 1493c308c0a90b691bd7ff42deac6143b36ccc01 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 26 Oct 2026 12:19:33 +0000 Subject: [PATCH 1/9] ROB-1706 Document the Platform MCP toolset switches and ask_holmes Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01TUT5BRVCTsJGeFM3eXZdnV --- .../exporting/platform-mcp-api.rst | 56 ++++++++++++++++++- 1 file changed, 54 insertions(+), 2 deletions(-) diff --git a/docs/configuration/exporting/platform-mcp-api.rst b/docs/configuration/exporting/platform-mcp-api.rst index d6fdbd8e9..62977ae02 100644 --- a/docs/configuration/exporting/platform-mcp-api.rst +++ b/docs/configuration/exporting/platform-mcp-api.rst @@ -16,7 +16,20 @@ A standard MCP `Streamable HTTP ` does, and returns the answer in markdown. An investigation can take seconds or minutes, longer than most MCP clients wait for one tool call, so the call is split in two: + +* ``ask_holmes`` waits up to ``wait_seconds`` (default 50, at most 280) for the answer. When the answer is ready in time, the result has ``status: "completed"`` and the ``answer``; otherwise it has ``status: "running"`` and a ``conversation_id``. +* ``get_holmes_answer`` waits on that ``conversation_id`` again, with the same ``wait_seconds``, and returns the same shape. Call it until the status is ``completed``. The investigation keeps running between calls, so a client that times out loses nothing. + +.. list-table:: + :widths: 20 15 65 + :header-rows: 1 + + * - Argument + - Required + - Description + * - ``question`` + - Yes + - The question, with every detail Holmes needs (namespace, workload or pod names, time window, what was observed). + * - ``cluster`` + - When more than one cluster can be asked + - The cluster whose Holmes answers. The error of a call without it names the clusters you can ask. + * - ``wait_seconds`` + - No + - How long the call waits for the answer. Keep it under your MCP client's tool timeout. + +Both tools answer with ``{"conversation_id", "cluster", "status", "answer", "ui_link"}``; ``ui_link`` opens the conversation in the Robusta UI. + +.. code-block:: json + + { + "conversation_id": "78170c9f-2403-43ac-88ed-d6d39efd90ed", + "cluster": "prod-eu", + "ui_link": "https://platform.robusta.dev/my-account/holmes/chat/78170c9f-2403-43ac-88ed-d6d39efd90ed", + "status": "completed", + "answer": "3 of the 12 pods in `checkout` restarted in the last hour ..." + } + +Only clusters whose Holmes agent takes conversations from the platform (Holmes 0.24 or later, with the conversation worker enabled) can be asked, and only those the key's owner may chat with. + Rate limits and errors ^^^^^^^^^^^^^^^^^^^^^^^ From 727940f4e071cdf92bcfd4b0d3ebbf5a4834c0e3 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 28 Oct 2026 08:17:51 +0000 Subject: [PATCH 2/9] ROB-1706 Describe list_available_clusters on its own Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01TUT5BRVCTsJGeFM3eXZdnV --- docs/configuration/exporting/platform-mcp-api.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/configuration/exporting/platform-mcp-api.rst b/docs/configuration/exporting/platform-mcp-api.rst index 62977ae02..652030f3a 100644 --- a/docs/configuration/exporting/platform-mcp-api.rst +++ b/docs/configuration/exporting/platform-mcp-api.rst @@ -29,7 +29,7 @@ Under that switch, each toolset the server exposes has its own switch (all on by * - **Ask Holmes** - ``ask_holmes``, ``get_holmes_answer`` — ask the Holmes agent of a cluster a question and get back its full investigation. * - **Cluster tools** - - ``list_available_clusters`` and the ``remote_*`` tools — run one of Holmes' cluster-local tools (kubectl, Prometheus, pod logs) on a cluster and get its raw output. + - The ``remote_*`` tools — run one of Holmes' cluster-local tools (kubectl, Prometheus, pod logs) on a cluster and get its raw output — and ``list_available_clusters``, which lists the clusters a ``remote_*`` tool can run on for you. Authentication ^^^^^^^^^^^^^^ From 01ca2401c1a333d4060853046a7feb38dddf2a19 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 1 Nov 2026 13:35:30 +0000 Subject: [PATCH 3/9] ROB-1706 Document ask_holmes_followup and stop_holmes_conversation Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01TUT5BRVCTsJGeFM3eXZdnV --- docs/configuration/exporting/platform-mcp-api.rst | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/configuration/exporting/platform-mcp-api.rst b/docs/configuration/exporting/platform-mcp-api.rst index 652030f3a..7708400b7 100644 --- a/docs/configuration/exporting/platform-mcp-api.rst +++ b/docs/configuration/exporting/platform-mcp-api.rst @@ -27,7 +27,7 @@ Under that switch, each toolset the server exposes has its own switch (all on by * - Toolset - Tools * - **Ask Holmes** - - ``ask_holmes``, ``get_holmes_answer`` — ask the Holmes agent of a cluster a question and get back its full investigation. + - ``ask_holmes``, ``get_holmes_answer``, ``ask_holmes_followup``, ``stop_holmes_conversation`` — ask the Holmes agent of a cluster a question, get back its full investigation, continue it, or stop it. * - **Cluster tools** - The ``remote_*`` tools — run one of Holmes' cluster-local tools (kubectl, Prometheus, pod logs) on a cluster and get its raw output — and ``list_available_clusters``, which lists the clusters a ``remote_*`` tool can run on for you. @@ -166,6 +166,11 @@ Both tools answer with ``{"conversation_id", "cluster", "status", "answer", "ui_ "answer": "3 of the 12 pods in `checkout` restarted in the last hour ..." } +Two more tools work on a conversation ``ask_holmes`` started: + +* ``ask_holmes_followup`` takes a ``conversation_id`` and the next ``question``, and waits like ``ask_holmes``. Holmes answers with the earlier questions, its findings and tool results as context, so use it to dig into an answer or redirect the investigation instead of asking afresh. The conversation must have ended first: one still ``running`` is refused, so wait for its answer with ``get_holmes_answer`` or stop it. +* ``stop_holmes_conversation`` ends an investigation that is still running, when its answer is no longer needed. The result has ``stopped: true`` and ``status: "stopped"``; a conversation that had already ended comes back with ``stopped: false`` and the status it ended in, and a later ``get_holmes_answer`` on a stopped conversation reports the stop instead of an answer. + Only clusters whose Holmes agent takes conversations from the platform (Holmes 0.24 or later, with the conversation worker enabled) can be asked, and only those the key's owner may chat with. Rate limits and errors From cc09bec20ba6e307b3c19ef28d4ffb956dc84572 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 1 Nov 2026 15:26:26 +0000 Subject: [PATCH 4/9] ROB-1706 Note the Holmes executor pool ask_holmes questions run on Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01TUT5BRVCTsJGeFM3eXZdnV --- docs/configuration/exporting/platform-mcp-api.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/configuration/exporting/platform-mcp-api.rst b/docs/configuration/exporting/platform-mcp-api.rst index 7708400b7..1d9a6d5db 100644 --- a/docs/configuration/exporting/platform-mcp-api.rst +++ b/docs/configuration/exporting/platform-mcp-api.rst @@ -137,6 +137,8 @@ Asking Holmes a question * ``ask_holmes`` waits up to ``wait_seconds`` (default 50, at most 280) for the answer. When the answer is ready in time, the result has ``status: "completed"`` and the ``answer``; otherwise it has ``status: "running"`` and a ``conversation_id``. * ``get_holmes_answer`` waits on that ``conversation_id`` again, with the same ``wait_seconds``, and returns the same shape. Call it until the status is ``completed``. The investigation keeps running between calls, so a client that times out loses nothing. +Questions asked this way run on the cluster's ``auto`` Holmes executor, the background pool that also runs auto-triage and bulk investigations, so they never delay a person's chat in the Robusta UI, which runs on ``manual``. + .. list-table:: :widths: 20 15 65 :header-rows: 1 From 25e1ceefe91242ec9d79b7ab9baea0a54c496055 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 1 Nov 2026 15:44:16 +0000 Subject: [PATCH 5/9] ROB-1706 Note the Holmes executor pool Chat API questions run on Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01TUT5BRVCTsJGeFM3eXZdnV --- docs/configuration/holmesgpt/holmes-chat-api.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/configuration/holmesgpt/holmes-chat-api.rst b/docs/configuration/holmesgpt/holmes-chat-api.rst index b085992bd..b582efefa 100644 --- a/docs/configuration/holmesgpt/holmes-chat-api.rst +++ b/docs/configuration/holmesgpt/holmes-chat-api.rst @@ -6,6 +6,8 @@ Holmes Chat API Use this endpoint to send questions to Holmes AI for root cause analysis. You can provide alert context and Holmes will investigate and return a detailed markdown analysis. +On clusters whose Holmes takes questions directly (no Robusta runner), the question runs on the cluster's ``auto`` Holmes executor, the background pool that also runs auto-triage and bulk investigations, so it never delays a person's chat in the Robusta UI. The pool can be resized per account with the ``conversation_executors`` account setting. + .. _holmes-chat-api: POST https://api.robusta.dev/api/holmes//chat From 7097cd5bae3dab47a539a6a2a374b39d370375cb Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 4 Nov 2026 15:32:06 +0000 Subject: [PATCH 6/9] ROB-1706 docs: ask_holmes default wait is 240s Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01TUT5BRVCTsJGeFM3eXZdnV --- docs/configuration/exporting/platform-mcp-api.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/configuration/exporting/platform-mcp-api.rst b/docs/configuration/exporting/platform-mcp-api.rst index 1d9a6d5db..a118c84b0 100644 --- a/docs/configuration/exporting/platform-mcp-api.rst +++ b/docs/configuration/exporting/platform-mcp-api.rst @@ -134,7 +134,7 @@ Asking Holmes a question ``ask_holmes`` starts a Holmes investigation on a cluster, the same way the :doc:`Holmes Chat API <../holmesgpt/holmes-chat-api>` does, and returns the answer in markdown. An investigation can take seconds or minutes, longer than most MCP clients wait for one tool call, so the call is split in two: -* ``ask_holmes`` waits up to ``wait_seconds`` (default 50, at most 280) for the answer. When the answer is ready in time, the result has ``status: "completed"`` and the ``answer``; otherwise it has ``status: "running"`` and a ``conversation_id``. +* ``ask_holmes`` waits up to ``wait_seconds`` (default 240, at most 280; pass a shorter wait when your MCP client's tool timeout is shorter) for the answer. When the answer is ready in time, the result has ``status: "completed"`` and the ``answer``; otherwise it has ``status: "running"`` and a ``conversation_id``. * ``get_holmes_answer`` waits on that ``conversation_id`` again, with the same ``wait_seconds``, and returns the same shape. Call it until the status is ``completed``. The investigation keeps running between calls, so a client that times out loses nothing. Questions asked this way run on the cluster's ``auto`` Holmes executor, the background pool that also runs auto-triage and bulk investigations, so they never delay a person's chat in the Robusta UI, which runs on ``manual``. From b835a2d19550e654d635d75bfe69dd5b786d3582 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 4 Nov 2026 15:47:54 +0000 Subject: [PATCH 7/9] ROB-1784 docs: ask_holmes reports progress over MCP Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01TUT5BRVCTsJGeFM3eXZdnV --- docs/configuration/exporting/platform-mcp-api.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/configuration/exporting/platform-mcp-api.rst b/docs/configuration/exporting/platform-mcp-api.rst index a118c84b0..37fb68f26 100644 --- a/docs/configuration/exporting/platform-mcp-api.rst +++ b/docs/configuration/exporting/platform-mcp-api.rst @@ -137,6 +137,8 @@ Asking Holmes a question * ``ask_holmes`` waits up to ``wait_seconds`` (default 240, at most 280; pass a shorter wait when your MCP client's tool timeout is shorter) for the answer. When the answer is ready in time, the result has ``status: "completed"`` and the ``answer``; otherwise it has ``status: "running"`` and a ``conversation_id``. * ``get_holmes_answer`` waits on that ``conversation_id`` again, with the same ``wait_seconds``, and returns the same shape. Call it until the status is ``completed``. The investigation keeps running between calls, so a client that times out loses nothing. +While a call waits, the server reports each step of the investigation (the tools Holmes runs, its plan, its intermediate notes) as MCP progress notifications to a client that asked for them: a ``tools/call`` carrying ``_meta.progressToken`` and ``Accept: text/event-stream`` is answered as an event stream of ``notifications/progress`` messages ending in the result. Claude Code and the official MCP SDKs do this on their own and reset their timeouts on each notification; a client that sends no token gets a plain JSON response. + Questions asked this way run on the cluster's ``auto`` Holmes executor, the background pool that also runs auto-triage and bulk investigations, so they never delay a person's chat in the Robusta UI, which runs on ``manual``. .. list-table:: From 6cfc951ce02de6674c43b4177a3f7ffe2d2cc0d9 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 4 Nov 2026 15:51:02 +0000 Subject: [PATCH 8/9] ROB-1784 docs: ask_holmes results list their steps Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01TUT5BRVCTsJGeFM3eXZdnV --- docs/configuration/exporting/platform-mcp-api.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/configuration/exporting/platform-mcp-api.rst b/docs/configuration/exporting/platform-mcp-api.rst index 37fb68f26..6d56c922f 100644 --- a/docs/configuration/exporting/platform-mcp-api.rst +++ b/docs/configuration/exporting/platform-mcp-api.rst @@ -134,7 +134,7 @@ Asking Holmes a question ``ask_holmes`` starts a Holmes investigation on a cluster, the same way the :doc:`Holmes Chat API <../holmesgpt/holmes-chat-api>` does, and returns the answer in markdown. An investigation can take seconds or minutes, longer than most MCP clients wait for one tool call, so the call is split in two: -* ``ask_holmes`` waits up to ``wait_seconds`` (default 240, at most 280; pass a shorter wait when your MCP client's tool timeout is shorter) for the answer. When the answer is ready in time, the result has ``status: "completed"`` and the ``answer``; otherwise it has ``status: "running"`` and a ``conversation_id``. +* ``ask_holmes`` waits up to ``wait_seconds`` (default 240, at most 280; pass a shorter wait when your MCP client's tool timeout is shorter) for the answer. When the answer is ready in time, the result has ``status: "completed"``, the ``answer`` and ``steps``, the tool calls behind the answer as ``{tool, description, failed?}`` in order (the first 50; ``steps_truncated: true`` when more ran); otherwise it has ``status: "running"`` and a ``conversation_id``. * ``get_holmes_answer`` waits on that ``conversation_id`` again, with the same ``wait_seconds``, and returns the same shape. Call it until the status is ``completed``. The investigation keeps running between calls, so a client that times out loses nothing. While a call waits, the server reports each step of the investigation (the tools Holmes runs, its plan, its intermediate notes) as MCP progress notifications to a client that asked for them: a ``tools/call`` carrying ``_meta.progressToken`` and ``Accept: text/event-stream`` is answered as an event stream of ``notifications/progress`` messages ending in the result. Claude Code and the official MCP SDKs do this on their own and reset their timeouts on each notification; a client that sends no token gets a plain JSON response. From 08fbb0ccf00a75495081846171f28e54ed35a8a5 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 4 Nov 2026 16:02:15 +0000 Subject: [PATCH 9/9] ROB-1784 docs: ask_holmes as MCP Tasks Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01TUT5BRVCTsJGeFM3eXZdnV --- docs/configuration/exporting/platform-mcp-api.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/configuration/exporting/platform-mcp-api.rst b/docs/configuration/exporting/platform-mcp-api.rst index 6d56c922f..6063495ab 100644 --- a/docs/configuration/exporting/platform-mcp-api.rst +++ b/docs/configuration/exporting/platform-mcp-api.rst @@ -139,6 +139,8 @@ Asking Holmes a question While a call waits, the server reports each step of the investigation (the tools Holmes runs, its plan, its intermediate notes) as MCP progress notifications to a client that asked for them: a ``tools/call`` carrying ``_meta.progressToken`` and ``Accept: text/event-stream`` is answered as an event stream of ``notifications/progress`` messages ending in the result. Claude Code and the official MCP SDKs do this on their own and reset their timeouts on each notification; a client that sends no token gets a plain JSON response. +A client that speaks `MCP Tasks `_ (protocol 2025-11-25, experimental) can run ``ask_holmes`` and ``ask_holmes_followup`` as tasks instead: a ``tools/call`` carrying ``task`` answers at once with a working task whose id is the ``conversation_id``, ``tasks/get`` polls it, ``tasks/result`` waits for the answer (the same result as ``get_holmes_answer``), and ``tasks/cancel`` stops it. A task is reachable by the API key that created it alone, is kept for as long as the conversation, and ``tasks/list`` is not served. + Questions asked this way run on the cluster's ``auto`` Holmes executor, the background pool that also runs auto-triage and bulk investigations, so they never delay a person's chat in the Robusta UI, which runs on ``manual``. .. list-table::