Skip to content

Commit bae83d4

Browse files
bobbyilievbobbyiliev
committed
docs: mcp split into 2 pages
1 parent 7f3b765 commit bae83d4

File tree

3 files changed

+259
-196
lines changed

3 files changed

+259
-196
lines changed

‎doc/user/content/integrations/_index.md‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -46,10 +46,11 @@ See also the following integration guides for BI tools:
4646
- [Connect to Materialize via HTTP](/integrations/http-api/)
4747
- [Connect to Materialize via WebSocket](/integrations/websocket-api/)
4848

49-
## Coding agents
49+
## AI agents
5050

51-
- [Built-in MCP Server](/integrations/mcp/)
52-
- [MCP Server (Python)](/integrations/llm/)
51+
- [MCP Server for Agents](/integrations/mcp-agents/) — built-in endpoint for exposing real-time data products to AI agents
52+
- [MCP Server for Observability](/integrations/mcp-observatory/) — built-in endpoint for AI-powered troubleshooting via system catalog
53+
- [MCP Server (Python)](/integrations/llm/) — standalone Python server with `stdio` and `sse` transport support, for use outside the built-in endpoints
5354
- [Coding Agent Skills](/integrations/coding-agent-skills/)
5455

5556
## Foreign data wrapper

doc/user/content/integrations/mcp.md renamed to doc/user/content/integrations/mcp-agents.md

Lines changed: 44 additions & 193 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
2-
title: Built-in MCP Server
3-
description: "Connect AI agents directly to Materialize's built-in MCP endpoints for real-time data access."
2+
title: MCP Server for Agents
3+
description: "Expose real-time data products to AI agents via Materialize's built-in MCP endpoint."
44
make_table_row_headers_searchable: true
55
menu:
66
main:
@@ -10,46 +10,37 @@ menu:
1010

1111
{{< private-preview />}}
1212

13-
Materialize provides built-in [Model Context Protocol
14-
(MCP)](https://modelcontextprotocol.io/) endpoints that let AI agents discover
13+
Materialize provides a built-in [Model Context Protocol
14+
(MCP)](https://modelcontextprotocol.io/) endpoint that lets AI agents discover
1515
and query your real-time data products over HTTP. The MCP interface is served
1616
directly by the database; no sidecar process or external server is required.
1717

18-
## MCP endpoints overview
18+
**Endpoint:** `POST /api/mcp/agents` (HTTP port, default `6876`)
1919

20-
| Endpoint | Path | Description |
21-
|----------|------|-------------|
22-
| **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`). |
23-
| **Observatory** | `/api/mcp/observatory` | Query `mz_*` system catalog tables for troubleshooting and observability. Available on the HTTP port (default `6876`). |
24-
25-
The endpoints use [JSON-RPC 2.0](https://www.jsonrpc.org/specification) over
26-
HTTP POST and support the MCP `initialize`, `tools/list`, and `tools/call`
20+
The endpoint uses [JSON-RPC 2.0](https://www.jsonrpc.org/specification) over
21+
HTTP POST and supports the MCP `initialize`, `tools/list`, and `tools/call`
2722
methods.
2823

29-
### Enabling / Disabling the MCP endpoints
24+
### Enabling the endpoint
3025

31-
MCP endpoints can be toggled at runtime using system parameters:
26+
The agents endpoint is disabled by default. Enable it at runtime using system
27+
parameters:
3228

3329
| Parameter | Default | Description |
3430
|-----------|---------|-------------|
3531
| `enable_mcp_agents` | `false` | Enable or disable the `/api/mcp/agents` endpoint. |
36-
| `enable_mcp_observatory` | `false` | Enable or disable the `/api/mcp/observatory` endpoint. |
3732
| `enable_mcp_agents_query_tool` | `false` | Show or hide the `query` tool on the agents endpoint. |
3833
| `mcp_max_response_size` | `1000000` | Maximum response size in bytes. Queries exceeding this limit return an error. |
3934

4035
```mzsql
41-
-- Disable the agents endpoint
42-
ALTER SYSTEM SET enable_mcp_agents = false;
43-
44-
-- Enable the query tool
45-
ALTER SYSTEM SET enable_mcp_agents_query_tool = true;
36+
ALTER SYSTEM SET enable_mcp_agents = true;
4637
```
4738

48-
When an endpoint is disabled, requests return HTTP 503 (Service Unavailable).
39+
When the endpoint is disabled, requests return HTTP 503 (Service Unavailable).
4940

5041
## Authentication and access control {#rbac}
5142

52-
Accessing the MCP endpoints requires [basic authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication#basic_authentication_scheme),
43+
Accessing the MCP endpoint requires [basic authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication#basic_authentication_scheme),
5344
just as connecting via a SQL client (e.g. `psql`). The authenticated role
5445
determines which data products are visible based on RBAC privileges.
5546

@@ -64,7 +55,7 @@ Use the credentials of a Materialize user or
6455
* **Password:** An [app password](/security/cloud/users-service-accounts/create-service-accounts/).
6556

6657
For production use, we recommend creating a dedicated service account and
67-
granting it a role with limited privileges (see below).
58+
granting it a role with limited privileges (see [Required privileges](#required-privileges)).
6859

6960
{{< /tab >}}
7061

@@ -100,7 +91,7 @@ workloads. This ensures agent queries do not consume resources from your other
10091
clusters, and limits visibility to only the data products you choose to expose.
10192

10293
```mzsql
103-
CREATE CLUSTER mcp_cluster SIZE 'xsmall';
94+
CREATE CLUSTER mcp_cluster SIZE '25cc';
10495
CREATE SCHEMA mcp_schema;
10596
```
10697

@@ -177,8 +168,11 @@ GRANT mcp_agent TO '<service-account-name>';
177168

178169
{{< tab "Self-Managed" >}}
179170

171+
Create a functional role for privileges, then assign it to a login role:
172+
180173
```mzsql
181-
CREATE ROLE mcp_agent LOGIN PASSWORD 'secret';
174+
-- Functional role (cannot log in, holds privileges)
175+
CREATE ROLE mcp_agent;
182176
183177
GRANT USAGE ON DATABASE materialize TO mcp_agent;
184178
GRANT USAGE ON SCHEMA mcp_schema TO mcp_agent;
@@ -190,21 +184,23 @@ GRANT USAGE ON CLUSTER mcp_cluster TO mcp_agent;
190184
-- and only see objects in mcp_schema by default.
191185
ALTER ROLE mcp_agent SET cluster TO mcp_cluster;
192186
ALTER ROLE mcp_agent SET search_path TO mcp_schema;
187+
188+
-- Login role (used for authentication)
189+
CREATE ROLE my_agent LOGIN PASSWORD 'secret';
190+
GRANT mcp_agent TO my_agent;
193191
```
194192

193+
You can create additional login roles and grant them the same `mcp_agent` role
194+
as needed.
195+
195196
{{< /tab >}}
196197

197198
{{< /tabs >}}
198199

199200
If any privilege is missing, the data product will not appear in the agent's
200201
tool list.
201202

202-
## Agents endpoint
203-
204-
**`POST /api/mcp/agents`**
205-
206-
The agents endpoint exposes your data products as MCP tools. It provides the
207-
following tools:
203+
## Tools
208204

209205
### `get_data_products`
210206

@@ -318,39 +314,6 @@ Execute a SQL `SELECT` statement against your data products.
318314
}
319315
```
320316

321-
## Observatory endpoint
322-
323-
**`POST /api/mcp/observatory`**
324-
325-
The observatory endpoint gives agents read-only access to the Materialize
326-
system catalog for troubleshooting and observability.
327-
328-
### `query_system_catalog`
329-
330-
Execute a SQL query restricted to `mz_*` system tables.
331-
332-
| Parameter | Type | Required | Description |
333-
|-----------|------|----------|-------------|
334-
| `sql_query` | string | Yes | `SELECT` query using only `mz_*` system tables. |
335-
336-
**Example response:**
337-
338-
```json
339-
{
340-
"jsonrpc": "2.0",
341-
"id": 1,
342-
"result": {
343-
"content": [
344-
{
345-
"type": "text",
346-
"text": "[\n [\n \"quickstart\",\n \"ready\"\n ],\n [\n \"mcp_cluster\",\n \"ready\"\n ]\n]"
347-
}
348-
],
349-
"isError": false
350-
}
351-
}
352-
```
353-
354317
## Client configuration
355318

356319
Replace `<host>` with your Materialize hostname (or region host for Cloud) and
@@ -360,68 +323,17 @@ encode your credentials in Base64:
360323
printf 'user:app_password' | base64
361324
```
362325

363-
### Claude Desktop
364-
365-
Add the following to your Claude Desktop MCP configuration
366-
(`claude_desktop_config.json`):
367-
368326
{{< tabs >}}
369327

370-
{{< tab "Cloud" >}}
328+
{{< tab "Claude Desktop" >}}
371329

372-
```json
373-
{
374-
"mcpServers": {
375-
"materialize": {
376-
"url": "https://<region-host>/api/mcp/agents",
377-
"headers": {
378-
"Authorization": "Basic <base64(user:app_password)>"
379-
}
380-
}
381-
}
382-
}
383-
```
384-
385-
{{< /tab >}}
386-
387-
{{< tab "Self-Managed" >}}
330+
Add to your Claude Desktop MCP configuration (`claude_desktop_config.json`):
388331

389332
```json
390333
{
391334
"mcpServers": {
392335
"materialize": {
393-
"url": "http://<host>:6876/api/mcp/agents",
394-
"headers": {
395-
"Authorization": "Basic <base64(username:password)>"
396-
}
397-
}
398-
}
399-
}
400-
```
401-
402-
{{< /tab >}}
403-
404-
{{< /tabs >}}
405-
406-
### Cursor
407-
408-
In Cursor's MCP settings (`.cursor/mcp.json`):
409-
410-
{{< tabs >}}
411-
412-
{{< tab "Cloud" >}}
413-
414-
```json
415-
{
416-
"mcpServers": {
417-
"materialize-agents": {
418-
"url": "https://<region-host>/api/mcp/agents",
419-
"headers": {
420-
"Authorization": "Basic <base64(user:app_password)>"
421-
}
422-
},
423-
"materialize-observatory": {
424-
"url": "https://<region-host>/api/mcp/observatory",
336+
"url": "https://<host>/api/mcp/agents",
425337
"headers": {
426338
"Authorization": "Basic <base64(user:app_password)>"
427339
}
@@ -432,52 +344,16 @@ In Cursor's MCP settings (`.cursor/mcp.json`):
432344

433345
{{< /tab >}}
434346

435-
{{< tab "Self-Managed" >}}
436-
437-
```json
438-
{
439-
"mcpServers": {
440-
"materialize-agents": {
441-
"url": "http://<host>:6876/api/mcp/agents",
442-
"headers": {
443-
"Authorization": "Basic <base64(username:password)>"
444-
}
445-
},
446-
"materialize-observatory": {
447-
"url": "http://<host>:6876/api/mcp/observatory",
448-
"headers": {
449-
"Authorization": "Basic <base64(username:password)>"
450-
}
451-
}
452-
}
453-
}
454-
```
455-
456-
{{< /tab >}}
457-
458-
{{< /tabs >}}
459-
460-
### Claude Code
347+
{{< tab "Claude Code" >}}
461348

462349
In your project's `.mcp.json`:
463350

464-
{{< tabs >}}
465-
466-
{{< tab "Cloud" >}}
467-
468351
```json
469352
{
470353
"mcpServers": {
471354
"materialize-agents": {
472355
"type": "http",
473-
"url": "https://<region-host>/api/mcp/agents",
474-
"headers": {
475-
"Authorization": "Basic <base64(user:app_password)>"
476-
}
477-
},
478-
"materialize-observatory": {
479-
"type": "http",
480-
"url": "https://<region-host>/api/mcp/observatory",
356+
"url": "https://<host>/api/mcp/agents",
481357
"headers": {
482358
"Authorization": "Basic <base64(user:app_password)>"
483359
}
@@ -488,23 +364,17 @@ In your project's `.mcp.json`:
488364

489365
{{< /tab >}}
490366

491-
{{< tab "Self-Managed" >}}
367+
{{< tab "Cursor" >}}
368+
369+
In Cursor's MCP settings (`.cursor/mcp.json`):
492370

493371
```json
494372
{
495373
"mcpServers": {
496374
"materialize-agents": {
497-
"type": "http",
498-
"url": "http://<host>:6876/api/mcp/agents",
375+
"url": "https://<host>/api/mcp/agents",
499376
"headers": {
500-
"Authorization": "Basic <base64(username:password)>"
501-
}
502-
},
503-
"materialize-observatory": {
504-
"type": "http",
505-
"url": "http://<host>:6876/api/mcp/observatory",
506-
"headers": {
507-
"Authorization": "Basic <base64(username:password)>"
377+
"Authorization": "Basic <base64(user:app_password)>"
508378
}
509379
}
510380
}
@@ -513,18 +383,12 @@ In your project's `.mcp.json`:
513383

514384
{{< /tab >}}
515385

516-
{{< /tabs >}}
517-
518-
### Generic HTTP client
386+
{{< tab "Generic HTTP" >}}
519387

520388
Any MCP-compatible client can connect by sending JSON-RPC 2.0 requests:
521389

522-
{{< tabs >}}
523-
524-
{{< tab "Cloud" >}}
525-
526390
```bash
527-
curl -X POST https://<region-host>/api/mcp/agents \
391+
curl -X POST https://<host>/api/mcp/agents \
528392
-H "Content-Type: application/json" \
529393
-H "Authorization: Basic <base64(user:app_password)>" \
530394
-d '{
@@ -536,27 +400,14 @@ curl -X POST https://<region-host>/api/mcp/agents \
536400

537401
{{< /tab >}}
538402

539-
{{< tab "Self-Managed" >}}
540-
541-
```bash
542-
curl -X POST http://<host>:6876/api/mcp/agents \
543-
-H "Content-Type: application/json" \
544-
-H "Authorization: Basic <base64(username:password)>" \
545-
-d '{
546-
"jsonrpc": "2.0",
547-
"id": 1,
548-
"method": "tools/list"
549-
}'
550-
```
551-
552-
{{< /tab >}}
553-
554403
{{< /tabs >}}
555404

556-
## Related Pages
405+
For self-managed deployments, use `http://<host>:6876` instead of `https://`.
406+
407+
## Related pages
557408

558-
- [MCP Server (Python)](/integrations/llm/): standalone Python MCP server
559-
for `stdio` and `sse` transports
409+
- [MCP Server for Observability](/integrations/mcp-observatory/)
410+
- [MCP Server (Python)](/integrations/llm/)
560411
- [Coding Agent Skills](/integrations/coding-agent-skills/)
561412
- [CREATE INDEX](/sql/create-index)
562413
- [COMMENT ON](/sql/comment-on)

0 commit comments

Comments
 (0)