docs: initial draft of built-in MCP server integration page by bobbyiliev · Pull Request #35604 · MaterializeInc/materialize

bobbyiliev · 2026-03-24T09:40:49Z

Initial draft of the built-in MCP server documentation.

Fixes https://linear.app/materializeinc/issue/DEX-6/mcp-user-documentation

github-actions · 2026-03-24T09:41:00Z

Thanks for opening this PR! Here are a few tips to help make the review process smooth for everyone.

PR title guidelines

Use imperative mood: "Fix X" not "Fixed X" or "Fixes X"
Be specific: "Fix panic in catalog sync when controller restarts" not "Fix bug" or "Update catalog code"
Prefix with area if helpful: compute: , storage: , adapter: , sql:

Pre-merge checklist

The PR title is descriptive and will make sense in the git log.
This PR has adequate test coverage / QA involvement has been duly considered. (trigger-ci for additional test/nightly runs)
If this PR includes major user-facing behavior changes, I have pinged the relevant PM to schedule a changelog post.
This PR has an associated up-to-date design doc, is a design doc (template), or is sufficiently small to not require a design.
If this PR evolves an existing $T ⇔ Proto$T mapping (possibly in a backwards-incompatible way), then it is tagged with a T-proto label.
If this PR will require changes to cloud orchestration or tests, there is a companion cloud PR to account for those changes that is tagged with the release-blocker label (example).

def- · 2026-03-24T14:32:09Z

doc/user/content/integrations/_index.md


- [MCP Server](/integrations/llm/)
+- [Built-in MCP Server](/integrations/mcp/)
+- [MCP Server (Python)](/integrations/llm/)


I'm not seeing the "(Python)" strangely:

Looking at https://preview.materialize.com/materialize/35604/integrations/llm/

Hmm, that's odd. The link text in _index.md says "MCP Server (Python)", might be a Hugo rendering issue with the sidebar. Let me check the frontmatter on the Python MCP page.

def- · 2026-03-24T14:32:48Z

doc/user/content/integrations/_index.md

+- [Built-in MCP Server](/integrations/mcp/)
+- [MCP Server (Python)](/integrations/llm/)


Seems a bit strange to have both, why do we need both? Is one legacy? Which should you use?

+1 to this, but maybe if we launch in public preview we don't remove the old one quite yet?

I'm also totally fine with removing it as soon as we default the flag to on.

The Python one supports stdio and sse transports and also gives users flexibility to either run it or deploy it separately if they don't want to enable it org wide. I'll add a short note clarifying the difference. Agree with Justin that we keep both for now and later on, deprecating the Python one.

@maheshwarip -- is the built-in mcp server launching as public preview? If yes, we probably should include {{< public-preview >}} on the mcp page.

Do we, per chance, want to create an AI agents folder under integrations folder and put these there? That way, the left hand side can be

Tools and integrations ... AI Agents > ...

Doing so ... I think we can later on move the define data products out of the MCP and LLM pages (definitely doesn't need to be done for this PR).

Added a private preview for now since the feature flags default to false. Shall I flip it to public preview? We can upgrade to public preview when we're ready to flip the defaults?

maheshwarip · 2026-03-25T18:48:38Z

doc/user/content/integrations/mcp.md

@@ -0,0 +1,469 @@
+---
+title: Built-in MCP Server


I'd recommend splitting up the docs into 1 page for the observatory, and another page for the agentic server!

Agree! Makes sense for when we flesh out the observatory docs more. For now both sections are pretty short, want me to split now or once the observatory is more complete?

Short docs are ok! I think it'll be easier to point a customer to the right doc if we have 1 page for each

maheshwarip · 2026-03-25T18:56:31Z

doc/user/content/integrations/mcp.md

+
+{{< /tabs >}}
+
+## Define data products


This section would go into the agent server.

Calling it data products is the right idea. But we use the phrase data products quite a bit with customers. I'd recommend being more verbose, and phrasing this as:

Define and document data products for your agents

The MCP server allows agents to discover and query documented data products. In Materialize, you can make the data product discoverable to customers by creating a Materialized View, adding an index, and adding a comment.

Neat, I like that! Done, rephrased to "Define and document data products for your agents" with the description you suggested.

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

maheshwarip · 2026-03-25T18:57:29Z

doc/user/content/integrations/mcp.md

+
+## Define data products
+
+A data product is any materialized view that has an


This is a note of feedback on the product itself: do we really need things to be indexed? Why not just have it be MVs with a comment?

Yes good question, this is more of a product decision. The index is what makes the data product appear in mz_mcp_data_products today (the view joins on mz_indexes). If we want MVs with just a comment to be sufficient, we'd need to change the underlying view. Worth a follow-up discussion!

maheshwarip · 2026-03-25T18:58:06Z

doc/user/content/integrations/mcp.md

+  'The unique identifier for the order';
+```
+
+### 4. Set RBAC permissions {#rbac}


Nit: I'd rephrase as create a role and permissions for your agent

Done! renamed to "Create a role and permissions for your agent".

maheshwarip · 2026-03-25T19:04:30Z

doc/user/content/integrations/mcp.md

+GRANT SELECT ON ALL TABLES IN SCHEMA mcp_schema TO mcp_agent;
+GRANT USAGE ON CLUSTER mcp_cluster TO mcp_agent;
+
+-- Lock the role to the dedicated cluster and schema


Huh, this is interesting - I didn't realize we can do this. What does this command do? Does it mean that mcp_agent can only operate with mcp_cluster?
ALTER ROLE mcp_agent SET cluster TO mcp_cluster

Added inline comments explaining it!

It basically allows all queries from that role run on mcp_cluster and only see objects in mcp_schema by default without having to explicitly set the cluster via an options arg.

doc/user/content/integrations/mcp.md

maheshwarip · 2026-03-25T19:07:51Z

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

+
+### `query`
+
+{{< note >}}


Hmm are we still shipping with the query tool? I'm glad we are if so, but I thought we weren't shipping this!

It's behind a separate flag (enable_mcp_agents_query_tool, default false), so it's not exposed by default. Documenting it here so users know it exists if they opt in. Should I remove this section or add a clearer callout that it's opt-in only?

maheshwarip · 2026-03-25T19:08:54Z

doc/user/content/integrations/mcp.md

+
+{{< /tabs >}}
+
+## Feature flags


I'd recommend phrasing this as "Enabling / Disabling the MCP endpoints" rather than "Feature Flags"

Done! Just renamed to "Enabling / Disabling the MCP endpoints".

kay-kim · 2026-03-30T12:25:21Z

doc/user/content/integrations/mcp.md

+* **User ID:** Your email address or service account name.
+* **Password:** An [app password](/security/cloud/users-service-accounts/create-service-accounts/).
+
+```


Why are we listing the agents endpoint here?

kay-kim · 2026-03-30T12:26:37Z

doc/user/content/integrations/mcp.md

+CREATE ROLE mcp_agent LOGIN PASSWORD 'secret';
+```
+
+The MCP endpoints are available on the HTTP listener port (default `6876`):


This might get a bit hidden.

Wondering if we can put it up where we discuss the end points.

kay-kim · 2026-03-30T12:27:24Z

doc/user/content/integrations/mcp.md

+
+Two endpoints are available:
+
+| Endpoint | Path | Purpose |


If we change Purpose -> Description, we could probably include the port info in here.

kay-kim · 2026-03-30T12:33:13Z

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

+
+{{< tab "Self-Managed" >}}
+
+```mzsql


Q: for sm, is it that it'll be 1 mcp_agent login for all?
Otherwise, we might want to make it more like Cloud and make mcp_agent a functional role and then assign to a particular login role.

kay-kim · 2026-03-30T12:38:25Z

doc/user/content/integrations/mcp.md

+  'The unique identifier for the order';
+```
+
+### 4. Create a role and permissions for your agent {#rbac}


So ... this doesn't quite fall under your heading of "Define and document data products for your agents".

bobbyiliev · 2026-03-31T13:31:04Z

Thanks for the review @kay-kim, just addressed all change requests!

kay-kim · 2026-04-01T20:15:15Z

doc/user/content/integrations/_index.md

+- [Built-in MCP Server](/integrations/mcp/)
+- [MCP Server (Python)](/integrations/llm/)


@maheshwarip -- is the built-in mcp server launching as public preview? If yes, we probably should include {{< public-preview >}} on the mcp page.

kay-kim · 2026-04-01T20:23:45Z

doc/user/content/integrations/_index.md

+- [Built-in MCP Server](/integrations/mcp/)
+- [MCP Server (Python)](/integrations/llm/)


Do we, per chance, want to create an AI agents folder under integrations folder and put these there? That way, the left hand side can be

Tools and integrations ... AI Agents > ...

Doing so ... I think we can later on move the define data products out of the MCP and LLM pages (definitely doesn't need to be done for this PR).

kay-kim · 2026-04-01T20:26:56Z

doc/user/content/integrations/mcp.md

+    weight: 23
+---
+
+Materialize includes built-in [Model Context Protocol


includes -> provides

That way, if we want to go "Starting in v26.blah, Materialize provides ..."

kay-kim · 2026-04-01T20:28:30Z

doc/user/content/integrations/mcp.md

+Materialize includes built-in [Model Context Protocol
+(MCP)](https://modelcontextprotocol.io/) endpoints that let AI agents discover
+and query your real-time data products over HTTP. No sidecar process or external
+server is required. The MCP interface is served directly by the database.


I'd flip the two sentence:

The MCP interface is served directly by the database; no sidecar process or external server is required.

kay-kim · 2026-04-01T20:37:56Z

doc/user/content/integrations/mcp.md

+| **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


Both -> The
speak -> use

kay-kim · 2026-04-01T20:53:31Z

doc/user/content/integrations/mcp.md

+  'The unique identifier for the order';
+```
+
+## Create a role and permissions for your agent {#rbac}


Should we move this up to Authentication and rename that section Authentication and Access Control (or something).

kay-kim · 2026-04-01T20:55:00Z

doc/user/content/integrations/mcp.md

+and query your real-time data products over HTTP. No sidecar process or external
+server is required. The MCP interface is served directly by the database.
+
+Two endpoints are available:


Maybe just make this a heading ## MCP endpoints overview or something?

kay-kim · 2026-04-01T20:55:24Z

doc/user/content/integrations/mcp.md

+
+{{< /tabs >}}
+
+## Enabling / Disabling the MCP endpoints


Wondering if this could go under the endpoints overview section as a child section

maheshwarip · 2026-03-25T19:16:28Z

doc/user/content/integrations/mcp.md

+| `cluster` | string | Yes | Exact cluster name from the data product details. |
+| `sql_query` | string | Yes | PostgreSQL-compatible `SELECT` statement. |
+
+## Observatory endpoint


I'd recommend adding more information here about the skills that we expose, as well as sample questions that the user can ask. For instance:

--
After you've connected to the observatory MCP server, your coding agents can answer questions such as:

Why is my my materialized view stale?

Has my source finished snapshotting yet?

How much memory is my cluster using?

maheshwarip · 2026-03-25T19:17:44Z

doc/user/content/integrations/mcp.md

@@ -0,0 +1,469 @@
+---
+title: Built-in MCP Server


Minor: I'd title this as MCP Server for Agents and MCP Server for Observability

maheshwarip · 2026-03-27T19:30:47Z

doc/user/content/integrations/mcp.md

@@ -0,0 +1,469 @@
+---
+title: Built-in MCP Server


Short docs are ok! I think it'll be easier to point a customer to the right doc if we have 1 page for each

maheshwarip · 2026-04-02T21:35:02Z

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

+clusters, and limits visibility to only the data products you choose to expose.
+
+```mzsql
+CREATE CLUSTER mcp_cluster SIZE 'xsmall';


Let's use cc sizes here, not tshirt!

bobbyiliev · 2026-04-03T12:55:44Z

thanks @maheshwarip! those should be all done now!

bobbyiliev force-pushed the mcp-docs branch 2 times, most recently from acc7f50 to 886d305 Compare March 24, 2026 14:19

bobbyiliev marked this pull request as ready for review March 24, 2026 14:20

bobbyiliev requested a review from a team as a code owner March 24, 2026 14:20

bobbyiliev requested review from jubrad, kay-kim and maheshwarip March 24, 2026 14:20

def- reviewed Mar 24, 2026

View reviewed changes

maheshwarip reviewed Mar 25, 2026

View reviewed changes

doc/user/content/integrations/mcp-agents.md Show resolved Hide resolved

maheshwarip reviewed Mar 25, 2026

View reviewed changes

doc/user/content/integrations/mcp.md Outdated Show resolved Hide resolved

maheshwarip reviewed Mar 25, 2026

View reviewed changes

maheshwarip requested changes Mar 25, 2026

View reviewed changes

bobbyiliev force-pushed the mcp-docs branch 2 times, most recently from b3b3028 to 8b29d50 Compare March 26, 2026 15:39

bobbyiliev requested review from def- and maheshwarip March 26, 2026 18:08

kay-kim reviewed Mar 30, 2026

View reviewed changes

bobbyiliev force-pushed the mcp-docs branch from 8b29d50 to 1391e6a Compare March 31, 2026 13:30

bobbyiliev requested a review from kay-kim March 31, 2026 13:31

bobbyiliev force-pushed the mcp-docs branch from 1391e6a to fbd039e Compare March 31, 2026 14:40

kay-kim reviewed Apr 1, 2026

View reviewed changes

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

1b55fff

mcp docs: add example responses

7f3b765

bobbyiliev force-pushed the mcp-docs branch from fbd039e to 7f3b765 Compare April 2, 2026 11:13

bobbyiliev requested a review from kay-kim April 2, 2026 11:15

maheshwarip reviewed Apr 2, 2026

View reviewed changes

bobbyiliev force-pushed the mcp-docs branch from f43a581 to bae83d4 Compare April 3, 2026 12:35

bobbyiliev requested a review from maheshwarip April 3, 2026 12:55

docs: mcp split into 2 pages

3b5b595

bobbyiliev force-pushed the mcp-docs branch from bae83d4 to 3b5b595 Compare April 3, 2026 17:34

		- [Built-in MCP Server](/integrations/mcp/)
		- [MCP Server (Python)](/integrations/llm/)


		## Define data products

		A data product is any materialized view that has an

Conversation

bobbyiliev commented Mar 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Mar 24, 2026

PR title guidelines

Pre-merge checklist

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Define and document data products for your agents

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bobbyiliev commented Mar 31, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

bobbyiliev commented Mar 24, 2026 •

edited

Loading