mcp docs: add example responses

Author: bobbyiliev

doc/user/content/integrations/llm.md

@@ -1,5 +1,5 @@
 ---
-title: MCP Server
+title: MCP Server (Python)
 description: "Learn how to integrate Materialize with Large Language Models (LLMs) using MCP"
 make_table_row_headers_searchable: true
 menu:

doc/user/content/integrations/mcp.md

@@ -15,10 +15,10 @@ server is required — the MCP interface is served directly by the database.
 
 Two endpoints are available:
 
-| Endpoint | Path | Purpose |
-|----------|------|---------|
-| **Agents** | `/api/mcp/agents` | Discover and read data products (indexed views with comments). Designed for customer-facing AI agents. |
-| **Observatory** | `/api/mcp/observatory` | Query `mz_*` system catalog tables for troubleshooting and observability. |
+| Endpoint | Path | Description |
+|----------|------|-------------|
+| **Agents** | `/api/mcp/agents` | Discover and read data products (indexed views with comments). Designed for customer-facing AI agents. Available on the HTTP port (default `6876`). |
+| **Observatory** | `/api/mcp/observatory` | Query `mz_*` system catalog tables for troubleshooting and observability. Available on the HTTP port (default `6876`). |
 
 Both endpoints speak [JSON-RPC 2.0](https://www.jsonrpc.org/specification) over
 HTTP POST and support the MCP `initialize`, `tools/list`, and `tools/call`
@@ -40,28 +40,23 @@ Use the credentials of a Materialize user or
 * **User ID:** Your email address or service account name.
 * **Password:** An [app password](/security/cloud/users-service-accounts/create-service-accounts/).
 
-```
-https://<region-host>/api/mcp/agents
-```
-
 For production use, we recommend creating a dedicated service account and
 granting it a role with [limited privileges](#rbac).
 
 {{< /tab >}}
 
 {{< tab "Self-Managed" >}}
 
-Use the credentials of a Materialize role with `LOGIN`:
+Create a functional role for MCP privileges, then assign it to a login role:
 
 ```mzsql
-CREATE ROLE mcp_agent LOGIN PASSWORD 'secret';
+CREATE ROLE mcp_agent;
+CREATE ROLE my_agent LOGIN PASSWORD 'secret';
+GRANT mcp_agent TO my_agent;
 ```
 
-The MCP endpoints are available on the HTTP listener port (default `6876`):
-
-```
-http://<host>:6876/api/mcp/agents
-```
+Authenticate using the login role credentials (`my_agent`). You can create
+additional login roles and grant them the same `mcp_agent` role as needed.
 
 {{< /tab >}}
 
@@ -118,7 +113,7 @@ COMMENT ON COLUMN mcp_schema.payment_status.order_id IS
   'The unique identifier for the order';
 ```
 
-### 4. Create a role and permissions for your agent {#rbac}
+## Create a role and permissions for your agent {#rbac}
 
 The role used to authenticate with the MCP endpoint must have:
 
@@ -194,6 +189,23 @@ Discover all available data products. Returns a list of names and descriptions.
 
 **Parameters:** None.
 
+**Example response:**
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": {
+    "content": [
+      {
+        "type": "text",
+        "text": "[\n  [\n    \"\\\"materialize\\\".\\\"mcp_schema\\\".\\\"payment_status\\\"\",\n    \"Given an order ID, return the current payment status.\",\n    \"mcp_cluster\"\n  ]\n]"
+      }
+    ]
+  }
+}
+```
+
 ### `get_data_product_details`
 
 Get the full schema (columns, types, index keys) for a specific data product.
@@ -202,6 +214,23 @@ Get the full schema (columns, types, index keys) for a specific data product.
 |-----------|------|----------|-------------|
 | `name` | string | Yes | Exact name from the `get_data_products` list. |
 
+**Example response:**
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": {
+    "content": [
+      {
+        "type": "text",
+        "text": "[\n  [\n    \"order_id\",\n    \"integer\",\n    true\n  ],\n  [\n    \"status\",\n    \"text\",\n    false\n  ]\n]"
+      }
+    ]
+  }
+}
+```
+
 ### `read_data_product`
 
 Read rows from a data product.
@@ -212,6 +241,23 @@ Read rows from a data product.
 | `limit` | integer | No | Maximum rows to return. Default: 500, max: 1000. |
 | `cluster` | string | No | Cluster override. If omitted, uses the cluster from the catalog. |
 
+**Example response:**
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": {
+    "content": [
+      {
+        "type": "text",
+        "text": "[\n  [\n    1001,\n    42,\n    \"shipped\",\n    \"2026-03-26T10:30:00Z\"\n  ]\n]"
+      }
+    ]
+  }
+}
+```
+
 ### `query`
 
 {{< note >}}
@@ -226,6 +272,23 @@ Execute a SQL `SELECT` statement against your data products.
 | `cluster` | string | Yes | Exact cluster name from the data product details. |
 | `sql_query` | string | Yes | PostgreSQL-compatible `SELECT` statement. |
 
+**Example response:**
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": {
+    "content": [
+      {
+        "type": "text",
+        "text": "[\n  [\n    42,\n    \"shipped\"\n  ]\n]"
+      }
+    ]
+  }
+}
+```
+
 ## Observatory endpoint
 
 **`POST /api/mcp/observatory`**
@@ -241,6 +304,23 @@ Execute a SQL query restricted to `mz_*` system tables.
 |-----------|------|----------|-------------|
 | `sql_query` | string | Yes | `SELECT` query using only `mz_*` system tables. |
 
+**Example response:**
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": {
+    "content": [
+      {
+        "type": "text",
+        "text": "[\n  [\n    \"quickstart\",\n    \"ready\"\n  ],\n  [\n    \"mcp_cluster\",\n    \"ready\"\n  ]\n]"
+      }
+    ]
+  }
+}
+```
+
 ## Client configuration
 
 Replace `<host>` with your Materialize hostname (or region host for Cloud) and
@@ -465,7 +545,7 @@ When an endpoint is disabled, requests return HTTP 503 (Service Unavailable).
 
 ## Related Pages
 
-- [MCP Server (Python)](/integrations/llm/) — standalone Python MCP server
+- [MCP Server (Python)](/integrations/llm/): standalone Python MCP server
   for `stdio` and `sse` transports
 - [Coding Agent Skills](/integrations/coding-agent-skills/)
 - [CREATE INDEX](/sql/create-index)