docs: initial draft of built-in MCP server integration page

doc/user/content/headless/mcp-troubleshooting.md

@@ -0,0 +1,69 @@
+## Troubleshooting
+
+### `unable to verify the first certificate`
+
+**Symptom:** Your MCP client (Claude Code, Cursor, etc.) returns an error like:
+
+```
+Error: SDK auth failed: unable to verify the first certificate
+```
+
+**Cause:** This error has two common causes:
+
+1. **Wrong protocol:** You're using `http://` but your deployment has TLS
+   enabled. Switch to `https://` in your MCP configuration.
+2. **Self-signed certificate:** Your Materialize deployment uses a self-signed
+   TLS certificate, which is the default for
+   [self-managed installations](/self-managed-deployments/). MCP clients built
+   on Node.js (including Claude Code) reject self-signed certificates by
+   default.
+
+**First, check your URL** — if you're using `http://`, try changing to
+`https://`. If that resolves the error, update your MCP configuration.
+
+**Fix:**
+
+For **Claude Code**, start with TLS verification disabled:
+
+```bash
+NODE_TLS_REJECT_UNAUTHORIZED=0 claude
+```
+
+For **Cursor** or other Node.js-based clients, set the same environment variable
+before launching:
+
+```bash
+export NODE_TLS_REJECT_UNAUTHORIZED=0
+```
+
+Alternatively, configure your deployment with a certificate from a trusted CA
+(e.g., [Let's Encrypt](https://letsencrypt.org/)) to avoid this issue entirely.
+
+### `HTTP 503 Service Unavailable`
+
+**Symptom:** Requests to the MCP endpoint return HTTP 503.
+
+**Cause:** The MCP endpoint is disabled. The feature flags default to `false`.
+
+**Fix:** Enable the endpoint via your
+[system parameters configuration](/self-managed-deployments/configuration-system-parameters/).
+See [Enabling the endpoint](#enabling-the-endpoint) above.
+
+### `HTTP 401 Unauthorized`
+
+**Symptom:** Requests return HTTP 401.
+
+**Cause:** Invalid or missing credentials. The Base64 token may be incorrectly
+encoded, or the user/password may be wrong.
+
+**Fix:** Re-encode your credentials and verify:
+
+```bash
+# Encode
+printf '<user>:<password>' | base64
+
+# Verify by decoding
+echo '<your-base64-token>' | base64 --decode
+```
+
+Make sure the decoded output matches `user:password` exactly.

doc/user/content/integrations/_index.md

@@ -46,9 +46,9 @@ See also the following integration guides for BI tools:
 - [Connect to Materialize via HTTP](/integrations/http-api/)
 - [Connect to Materialize via WebSocket](/integrations/websocket-api/)
 
-## Coding agents
+## AI agents
 
-- [MCP Server](/integrations/llm/)
+- [MCP Server for Developers](/integrations/mcp-server/mcp-developer/) — built-in endpoint for AI-powered troubleshooting via system catalog
 - [Coding Agent Skills](/integrations/coding-agent-skills/)
 
 ## Foreign data wrapper

doc/user/content/integrations/mcp-server/_index.md

@@ -0,0 +1,28 @@
+---
+title: "MCP Server"
+description: "Learn how to integrate with Materialize's built-in MCP endpoints."
+disable_list: true
+menu:
+  main:
+    parent: integrations
+    name: "MCP Server"
+    identifier: mcp-server
+    weight: 20
+---
+
+Materialize provides built-in Model Context Protocol (MCP) endpoints that AI
+agents can use. The MCP interface is served directly by the database; no sidecar
+process or external server is required.
+
+## MCP endpoints overview
+
+| Endpoint | Path | Description |
+|----------|------|-------------|
+| **Developer** | `/api/mcp/developer` | Read `mz_*` system catalog tables for troubleshooting and observability. <br>For details, see [MCP Server for developer](/integrations/mcp-server/mcp-developer/).|
+
+## See also
+
+- [MCP Server
+  Troubleshooting](/integrations/mcp-server/mcp-server-troubleshooting/)
+- [Appendix: MCP Server (Python)](/integrations/mcp-server/llm) for locally-run,
+  separate MCP Server.

doc/user/content/integrations/llm.md → doc/user/content/integrations/mcp-server/llm.md

@@ -1,13 +1,21 @@
 ---
-title: MCP Server
+title: "Appendix: MCP Server (Python)"
 description: "Learn how to integrate Materialize with Large Language Models (LLMs) using MCP"
 make_table_row_headers_searchable: true
 menu:
   main:
-    parent: "integrations"
-    weight: 24
+    parent: "mcp-server"
+    weight: 90
+aliases:
+  - /integrations/llm/
 ---
 
+{{< annotation type="Disambiguation">}}
+This page provides information on the locally-run, separate MCP Server.
+For documentation on using the new built-in MCP Server endpoints, see:
+- [MCP Server for Developer](/integrations/mcp-server/mcp-developer/)
+{{< /annotation >}}
+
 The [Model Context Protocol (MCP) Server for Materialize](https://materialize.com/blog/materialize-turns-views-into-tools-for-agents/) lets large language models (LLMs) call your indexed views as real-time tools.
 The MCP Server automatically turns any indexed view with a comment into a callable, typed interface that LLMs can use to fetch structured, up-to-date answers—directly from the database.
 

doc/user/content/integrations/mcp-server/mcp-agents-config.md

@@ -0,0 +1,74 @@
+---
+title: Agents endpoint configuration
+description: "Configuration for /api/mcp/agents endpoint."
+make_table_row_headers_searchable: true
+draft: true
+menu:
+  main:
+    parent: "mcp-server-agents"
+    weight: 20
+    identifier: "agents-endpoint-configuration"
+---
+
+## Available configuration parameters
+
+The following configurations are available for the `/api/mcp/agents` endpoint:
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `enable_mcp_agents` | `true` | Enable or disable the `/api/mcp/agents` endpoint. When disabled, requests return `HTTP 503 (Service Unavailable)`.|
+| `enable_mcp_agents_query_tool` | `true` | Show or hide the `query` tool on the agents endpoint. |
+| `mcp_max_response_size` | `1000000` | Maximum response size in bytes. Queries exceeding this limit return an error. |
+
+## Example: Enable endpoint
+
+To enable the `/api/mcp/agents` endpoint:
+
+{{< tabs >}}
+
+{{< tab "Cloud" >}}
+
+Contact [Materialize support](https://materialize.com/docs/support/) to
+enable/disable the MCP agents endpoint for your environment.
+{{< /tab >}}
+
+{{< tab "Self-Managed" >}}
+
+Enable the endpoint using one of these methods:
+
+**Option 1: Configuration file**
+
+Set the parameter in your
+[system parameters configuration file](/self-managed-deployments/configuration-system-parameters/):
+
+```yaml
+system_parameters:
+  enable_mcp_agents: "true"
+```
+
+**Option 2: Terraform**
+
+Set the parameter via the [Materialize Terraform module](https://github.com/MaterializeInc/materialize-terraform-self-managed):
+
+```hcl
+system_parameters = {
+  enable_mcp_agents = "true"
+}
+```
+
+**Option 3: SQL**
+
+Connect as `mz_system` and run:
+
+```mzsql
+ALTER SYSTEM SET enable_mcp_agents = true;
+```
+
+{{< note >}}
+These parameters are only accessible to the `mz_system` and `mz_support`
+roles. Regular database users cannot view or modify them.
+{{< /note >}}
+
+{{< /tab >}}
+
+{{< /tabs >}}