[9.2] [API docs][agent builder] Add warnings to MCP + A2A REST routes (#241856) (#242093)

{defaultPrDescription}

<!--BACKPORT {commits} BACKPORT-->

Author: leemthompo

oas_docs/bundle.json

@@ -860,7 +860,7 @@
     },
     "/api/agent_builder/a2a/{agentId}": {
       "post": {
-        "description": "Handle A2A (Agent-to-Agent) task requests. Use this endpoint to process inter-agent communication using JSON-RPC 2.0 protocol.<br/><br/>[Required authorization] Route required privileges: read_onechat.",
+        "description": "WARNING: This endpoint is designed for A2A protocol clients and should not be used directly via REST APIs. Use an A2A SDK or A2A Inspector instead.<br/><br/>[Required authorization] Route required privileges: read_onechat.",
         "operationId": "post-agent-builder-a2a-agentid",
         "parameters": [
           {
@@ -878,7 +878,7 @@
             "application/json": {
               "examples": {
                 "a2aTaskRequestExample": {
-                  "description": "Example request for A2A Task Endpoint",
+                  "description": "WARNING: DO NOT USE THIS ENDPOINT VIA REST API. These examples are auto-generated and should not be run. Integrate with A2A using an A2A SDK or A2A Inspector instead.",
                   "value": {
                     "id": "task-123",
                     "jsonrpc": "2.0",
@@ -1967,15 +1967,15 @@
     },
     "/api/agent_builder/mcp": {
       "post": {
-        "description": "Communicate with the MCP server via JSON-RPC 2.0. MCP is designed for AI clients like Claude Desktop, Cursor, and VS Code extensions to access your Elastic tools. Use this endpoint for testing MCP connectivity or debugging protocol communication. This endpoint requires JSON-RPC formatting and will not work from the Dev Tools Console.<br/><br/>[Required authorization] Route required privileges: read_onechat.",
+        "description": "WARNING: This endpoint is designed for MCP clients (Claude Desktop, Cursor, VS Code, etc.) and should not be used directly via REST APIs. Use MCP Inspector or native MCP clients instead.<br/><br/>[Required authorization] Route required privileges: read_onechat.",
         "operationId": "post-agent-builder-mcp",
         "parameters": [],
         "requestBody": {
           "content": {
             "application/json": {
               "examples": {
                 "mcpInitializeRequestExample": {
-                  "description": "Example request to initalise communication over MCP protocol",
+                  "description": "WARNING: DO NOT USE THIS ENDPOINT VIA REST API. These examples are auto-generated and should not be run. Integrate with MCP using MCP Inspector or native MCP clients (Claude Desktop, Cursor, VS Code) instead.",
                   "value": {
                     "id": 1,
                     "jsonrpc": "2.0",

oas_docs/bundle.serverless.json

@@ -860,7 +860,7 @@
     },
     "/api/agent_builder/a2a/{agentId}": {
       "post": {
-        "description": "Handle A2A (Agent-to-Agent) task requests. Use this endpoint to process inter-agent communication using JSON-RPC 2.0 protocol.<br/><br/>[Required authorization] Route required privileges: read_onechat.",
+        "description": "WARNING: This endpoint is designed for A2A protocol clients and should not be used directly via REST APIs. Use an A2A SDK or A2A Inspector instead.<br/><br/>[Required authorization] Route required privileges: read_onechat.",
         "operationId": "post-agent-builder-a2a-agentid",
         "parameters": [
           {
@@ -878,7 +878,7 @@
             "application/json": {
               "examples": {
                 "a2aTaskRequestExample": {
-                  "description": "Example request for A2A Task Endpoint",
+                  "description": "WARNING: DO NOT USE THIS ENDPOINT VIA REST API. These examples are auto-generated and should not be run. Integrate with A2A using an A2A SDK or A2A Inspector instead.",
                   "value": {
                     "id": "task-123",
                     "jsonrpc": "2.0",
@@ -1967,15 +1967,15 @@
     },
     "/api/agent_builder/mcp": {
       "post": {
-        "description": "Communicate with the MCP server via JSON-RPC 2.0. MCP is designed for AI clients like Claude Desktop, Cursor, and VS Code extensions to access your Elastic tools. Use this endpoint for testing MCP connectivity or debugging protocol communication. This endpoint requires JSON-RPC formatting and will not work from the Dev Tools Console.<br/><br/>[Required authorization] Route required privileges: read_onechat.",
+        "description": "WARNING: This endpoint is designed for MCP clients (Claude Desktop, Cursor, VS Code, etc.) and should not be used directly via REST APIs. Use MCP Inspector or native MCP clients instead.<br/><br/>[Required authorization] Route required privileges: read_onechat.",
         "operationId": "post-agent-builder-mcp",
         "parameters": [],
         "requestBody": {
           "content": {
             "application/json": {
               "examples": {
                 "mcpInitializeRequestExample": {
-                  "description": "Example request to initalise communication over MCP protocol",
+                  "description": "WARNING: DO NOT USE THIS ENDPOINT VIA REST API. These examples are auto-generated and should not be run. Integrate with MCP using MCP Inspector or native MCP clients (Claude Desktop, Cursor, VS Code) instead.",
                   "value": {
                     "id": 1,
                     "jsonrpc": "2.0",

oas_docs/output/kibana.serverless.yaml

@@ -893,7 +893,7 @@ paths:
 
         Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
 
-        Handle A2A (Agent-to-Agent) task requests. Use this endpoint to process inter-agent communication using JSON-RPC 2.0 protocol.<br/><br/>[Required authorization] Route required privileges: read_onechat.
+        WARNING: This endpoint is designed for A2A protocol clients and should not be used directly via REST APIs. Use an A2A SDK or A2A Inspector instead.<br/><br/>[Required authorization] Route required privileges: read_onechat.
       operationId: post-agent-builder-a2a-agentid
       parameters:
         - description: The unique identifier of the agent to send the A2A task to.
@@ -907,7 +907,7 @@ paths:
           application/json:
             examples:
               a2aTaskRequestExample:
-                description: Example request for A2A Task Endpoint
+                description: 'WARNING: DO NOT USE THIS ENDPOINT VIA REST API. These examples are auto-generated and should not be run. Integrate with A2A using an A2A SDK or A2A Inspector instead.'
                 value:
                   id: task-123
                   jsonrpc: '2.0'
@@ -1751,15 +1751,15 @@ paths:
 
         Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
 
-        Communicate with the MCP server via JSON-RPC 2.0. MCP is designed for AI clients like Claude Desktop, Cursor, and VS Code extensions to access your Elastic tools. Use this endpoint for testing MCP connectivity or debugging protocol communication. This endpoint requires JSON-RPC formatting and will not work from the Dev Tools Console.<br/><br/>[Required authorization] Route required privileges: read_onechat.
+        WARNING: This endpoint is designed for MCP clients (Claude Desktop, Cursor, VS Code, etc.) and should not be used directly via REST APIs. Use MCP Inspector or native MCP clients instead.<br/><br/>[Required authorization] Route required privileges: read_onechat.
       operationId: post-agent-builder-mcp
       parameters: []
       requestBody:
         content:
           application/json:
             examples:
               mcpInitializeRequestExample:
-                description: Example request to initalise communication over MCP protocol
+                description: 'WARNING: DO NOT USE THIS ENDPOINT VIA REST API. These examples are auto-generated and should not be run. Integrate with MCP using MCP Inspector or native MCP clients (Claude Desktop, Cursor, VS Code) instead.'
                 value:
                   id: 1
                   jsonrpc: '2.0'

oas_docs/output/kibana.yaml

@@ -958,7 +958,7 @@ paths:
 
         Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
 
-        Handle A2A (Agent-to-Agent) task requests. Use this endpoint to process inter-agent communication using JSON-RPC 2.0 protocol.<br/><br/>[Required authorization] Route required privileges: read_onechat.
+        WARNING: This endpoint is designed for A2A protocol clients and should not be used directly via REST APIs. Use an A2A SDK or A2A Inspector instead.<br/><br/>[Required authorization] Route required privileges: read_onechat.
       operationId: post-agent-builder-a2a-agentid
       parameters:
         - description: The unique identifier of the agent to send the A2A task to.
@@ -972,7 +972,7 @@ paths:
           application/json:
             examples:
               a2aTaskRequestExample:
-                description: Example request for A2A Task Endpoint
+                description: 'WARNING: DO NOT USE THIS ENDPOINT VIA REST API. These examples are auto-generated and should not be run. Integrate with A2A using an A2A SDK or A2A Inspector instead.'
                 value:
                   id: task-123
                   jsonrpc: '2.0'
@@ -1816,15 +1816,15 @@ paths:
 
         Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
 
-        Communicate with the MCP server via JSON-RPC 2.0. MCP is designed for AI clients like Claude Desktop, Cursor, and VS Code extensions to access your Elastic tools. Use this endpoint for testing MCP connectivity or debugging protocol communication. This endpoint requires JSON-RPC formatting and will not work from the Dev Tools Console.<br/><br/>[Required authorization] Route required privileges: read_onechat.
+        WARNING: This endpoint is designed for MCP clients (Claude Desktop, Cursor, VS Code, etc.) and should not be used directly via REST APIs. Use MCP Inspector or native MCP clients instead.<br/><br/>[Required authorization] Route required privileges: read_onechat.
       operationId: post-agent-builder-mcp
       parameters: []
       requestBody:
         content:
           application/json:
             examples:
               mcpInitializeRequestExample:
-                description: Example request to initalise communication over MCP protocol
+                description: 'WARNING: DO NOT USE THIS ENDPOINT VIA REST API. These examples are auto-generated and should not be run. Integrate with MCP using MCP Inspector or native MCP clients (Claude Desktop, Cursor, VS Code) instead.'
                 value:
                   id: 1
                   jsonrpc: '2.0'

x-pack/platform/plugins/shared/onechat/server/routes/a2a.ts

@@ -83,7 +83,7 @@ export function registerA2ARoutes({
       access: 'public',
       summary: 'Send A2A task',
       description:
-        'Handle A2A (Agent-to-Agent) task requests. Use this endpoint to process inter-agent communication using JSON-RPC 2.0 protocol.',
+        'WARNING: This endpoint is designed for A2A protocol clients and should not be used directly via REST APIs. Use an A2A SDK or A2A Inspector instead.',
       options: {
         tags: ['a2a', 'oas-tag:agent builder'],
         xsrfRequired: false,

x-pack/platform/plugins/shared/onechat/server/routes/examples/a2a_task.yaml

@@ -3,7 +3,7 @@ requestBody:
     application/json:
       examples:
         a2aTaskRequestExample:
-          description: "Example request for A2A Task Endpoint"
+          description: "WARNING: DO NOT USE THIS ENDPOINT VIA REST API. These examples are auto-generated and should not be run. Integrate with A2A using an A2A SDK or A2A Inspector instead."
           value:
             jsonrpc: "2.0"
             method: "complete"

x-pack/platform/plugins/shared/onechat/server/routes/examples/mcp_initialize.yaml

@@ -3,7 +3,7 @@ requestBody:
     application/json:
       examples:
         mcpInitializeRequestExample:
-          description: "Example request to initalise communication over MCP protocol"
+          description: "WARNING: DO NOT USE THIS ENDPOINT VIA REST API. These examples are auto-generated and should not be run. Integrate with MCP using MCP Inspector or native MCP clients (Claude Desktop, Cursor, VS Code) instead."
           value:
             jsonrpc: "2.0"
             method: "initialize"

x-pack/platform/plugins/shared/onechat/server/routes/mcp.ts

@@ -31,7 +31,7 @@ export function registerMCPRoutes({ router, getInternalServices, logger }: Route
       access: 'public',
       summary: 'MCP server',
       description:
-        'Communicate with the MCP server via JSON-RPC 2.0. MCP is designed for AI clients like Claude Desktop, Cursor, and VS Code extensions to access your Elastic tools. Use this endpoint for testing MCP connectivity or debugging protocol communication. This endpoint requires JSON-RPC formatting and will not work from the Dev Tools Console.',
+        'WARNING: This endpoint is designed for MCP clients (Claude Desktop, Cursor, VS Code, etc.) and should not be used directly via REST APIs. Use MCP Inspector or native MCP clients instead.',
       options: {
         tags: ['mcp', 'oas-tag:agent builder'],
         xsrfRequired: false,