ROB-1706 Document the Platform MCP toolset switches and the Ask Holmes tools

docs/configuration/exporting/platform-mcp-api.rst

@@ -16,7 +16,20 @@ A standard MCP `Streamable HTTP <https://modelcontextprotocol.io/specification/2
 Enabling external access
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Cross-cluster tool calls from an external MCP client are opt-in per account. Turn on **Robusta MCP Server Enabled** under **Settings → AI Assistant → MCP Server Settings** before an API key can list or call any ``remote_*`` tool. It is off by default.
+Access from an external MCP client is opt-in per account. Turn on **Robusta MCP Server Enabled** under **Settings → MCP Server** before an API key can list or call any tool. It is off by default.
+
+Under that switch, each toolset the server exposes has its own switch (all on by default once the server is enabled):
+
+.. list-table::
+   :widths: 25 75
+   :header-rows: 1
+
+   * - Toolset
+     - Tools
+   * - **Ask Holmes**
+     - ``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.
 
 Authentication
 ^^^^^^^^^^^^^^
@@ -112,10 +125,60 @@ For Claude Desktop or any generic MCP client (``mcp.json``):
 What an API key can call
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
-An API key is treated as an external caller and can only reach the cross-cluster ``remote_*`` tools (for example, listing available clusters and dispatching a tool call to one of them). It cannot call the static Slack, Teams, or incident-triage tools — those are reserved for Holmes' own internal use of this endpoint.
+An API key is treated as an external caller and can only reach the toolsets above. It cannot call the Slack, Teams, or incident-triage tools — those are reserved for Holmes' own internal use of this endpoint.
 
 Calls run with the RBAC of the user who created the API key, not as an account-wide superuser: a key only reaches the clusters and namespaces its owner can already access. Deleting or demoting that user's access also narrows what the key can do.
 
+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"``, 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.
+
+A client that speaks `MCP Tasks <https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/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::
+   :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 ..."
+    }
+
+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
 ^^^^^^^^^^^^^^^^^^^^^^^
 

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/<account_id>/chat