docs: initial draft of built-in MCP server integration page#35604
docs: initial draft of built-in MCP server integration page#35604bobbyiliev wants to merge 9 commits intoMaterializeInc:mainfrom
Conversation
|
Thanks for opening this PR! Here are a few tips to help make the review process smooth for everyone. PR title guidelines
Pre-merge checklist
|
bobbyiliev
force-pushed
the
mcp-docs
branch
2 times, most recently
from
acc7f50 to
886d305
Compare
|
|
||
| - [MCP Server](/integrations/llm/) | ||
| - [Built-in MCP Server](/integrations/mcp/) | ||
| - [MCP Server (Python)](/integrations/llm/) |
There was a problem hiding this comment.
I'm not seeing the "(Python)" strangely:
Looking at https://preview.materialize.com/materialize/35604/integrations/llm/
There was a problem hiding this comment.
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.
| - [Built-in MCP Server](/integrations/mcp/) | ||
| - [MCP Server (Python)](/integrations/llm/) |
There was a problem hiding this comment.
Seems a bit strange to have both, why do we need both? Is one legacy? Which should you use?
There was a problem hiding this comment.
+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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
@maheshwarip -- is the built-in mcp server launching as public preview? If yes, we probably should include {{< public-preview >}} on the mcp page.
There was a problem hiding this comment.
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).
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
I'd love for us to launch the built-in MCP server in public preview (i'll start a slack thread so that this gets posted broadly!). We can keep the flags off until this actually launches of course. Ideally it is enabled by default.
I vote we move the legacy python MCP server to an appendix section! @kay-kim has a plan for this :)
There was a problem hiding this comment.
Will add a patch to this branch so that we get a clearer idea of what we're thinking.
There was a problem hiding this comment.
The patch will have the following:
There was a problem hiding this comment.
Will patch using the new Console MCP connect feature: #35902
doc/user/content/integrations/mcp.md
Outdated
|
|
||
| ## Define data products | ||
|
|
||
| A data product is any materialized view that has an |
There was a problem hiding this comment.
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?
There was a problem hiding this 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!
doc/user/content/integrations/mcp.md
Outdated
| 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 |
There was a problem hiding this comment.
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
There was a problem hiding this comment.
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.
|
|
||
| ### `query` | ||
|
|
||
| {{< note >}} |
There was a problem hiding this comment.
Hmm are we still shipping with the query tool? I'm glad we are if so, but I thought we weren't shipping this!
There was a problem hiding this comment.
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?
bobbyiliev
force-pushed
the
mcp-docs
branch
2 times, most recently
from
b3b3028 to
8b29d50
Compare
doc/user/content/integrations/mcp.md
Outdated
| * **User ID:** Your email address or service account name. | ||
| * **Password:** An [app password](/security/cloud/users-service-accounts/create-service-accounts/). | ||
|
|
||
| ``` |
There was a problem hiding this comment.
Why are we listing the agents endpoint here?
doc/user/content/integrations/mcp.md
Outdated
| CREATE ROLE mcp_agent LOGIN PASSWORD 'secret'; | ||
| ``` | ||
|
|
||
| The MCP endpoints are available on the HTTP listener port (default `6876`): |
There was a problem hiding this comment.
This might get a bit hidden.
Wondering if we can put it up where we discuss the end points.
doc/user/content/integrations/mcp.md
Outdated
|
|
||
| Two endpoints are available: | ||
|
|
||
| | Endpoint | Path | Purpose | |
There was a problem hiding this comment.
If we change Purpose -> Description, we could probably include the port info in here.
|
|
||
| {{< tab "Self-Managed" >}} | ||
|
|
||
| ```mzsql |
There was a problem hiding this comment.
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.
doc/user/content/integrations/mcp.md
Outdated
| 'The unique identifier for the order'; | ||
| ``` | ||
|
|
||
| ### 4. Create a role and permissions for your agent {#rbac} |
There was a problem hiding this comment.
So ... this doesn't quite fall under your heading of "Define and document data products for your agents".
|
Thanks for the review @kay-kim, just addressed all change requests! |
| - [Built-in MCP Server](/integrations/mcp/) | ||
| - [MCP Server (Python)](/integrations/llm/) |
There was a problem hiding this comment.
@maheshwarip -- is the built-in mcp server launching as public preview? If yes, we probably should include {{< public-preview >}} on the mcp page.
| - [Built-in MCP Server](/integrations/mcp/) | ||
| - [MCP Server (Python)](/integrations/llm/) |
There was a problem hiding this comment.
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).
doc/user/content/integrations/mcp.md
Outdated
| weight: 23 | ||
| --- | ||
|
|
||
| Materialize includes built-in [Model Context Protocol |
There was a problem hiding this comment.
includes -> provides
That way, if we want to go "Starting in v26.blah, Materialize provides ..."
doc/user/content/integrations/mcp.md
Outdated
| 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. |
There was a problem hiding this comment.
I'd flip the two sentence:
The MCP interface is served directly by the database; no sidecar process or external server is required.
doc/user/content/integrations/mcp.md
Outdated
| | **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 |
doc/user/content/integrations/mcp.md
Outdated
| 'The unique identifier for the order'; | ||
| ``` | ||
|
|
||
| ## Create a role and permissions for your agent {#rbac} |
There was a problem hiding this comment.
Should we move this up to Authentication and rename that section Authentication and Access Control (or something).
doc/user/content/integrations/mcp.md
Outdated
| 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: |
There was a problem hiding this comment.
Maybe just make this a heading ## MCP endpoints overview or something?
doc/user/content/integrations/mcp.md
Outdated
|
|
||
| {{< /tabs >}} | ||
|
|
||
| ## Enabling / Disabling the MCP endpoints |
There was a problem hiding this comment.
Wondering if this could go under the endpoints overview section as a child section
|
thanks @maheshwarip! those should be all done now! |
|
|
||
| {{< tab "Self-Managed" >}} | ||
|
|
||
| Use your Materialize host and the HTTP port (default `6876`): |
There was a problem hiding this comment.
I think we should give users more information here - I'd recommend being super verbose about how to find the Materialize hostname. Could we give them the k8s command or the terraform command to run to find the hostname, so that it's a simple copy paste?
|
|
||
| {{< tab "Self-Managed" >}} | ||
|
|
||
| Use the login role credentials you created for MCP access (see |
There was a problem hiding this comment.
Should we add the explicit instructions here rather than making the user navigate elsewhere? I think the ideal flow here would be to just say CREATE USER <> WITH LOGIN PASSWORD <>
doc/user/content/integrations/llm.md
Outdated
| @@ -1,5 +1,5 @@ | |||
| --- | |||
| title: MCP Server | |||
| title: MCP Server (Python) | |||
There was a problem hiding this comment.
Same note as above: I'm ok with us un-documenting the python MCP server
|
good points @maheshwarip! those should be all done now! good for another review. |
|
|
||
| {{< /tabs >}} | ||
|
|
||
| ### Enabling the endpoint |
There was a problem hiding this comment.
If we launch as public preview, could we put this in a separate section called "Disabling the endpoint"?
| The endpoint uses [JSON-RPC 2.0](https://www.jsonrpc.org/specification) over | ||
| HTTP POST and supports the MCP `initialize`, `tools/list`, and `tools/call` | ||
| methods. | ||
|
|
There was a problem hiding this comment.
I'd recommend that we include a note here for customers to install the materialize coding agent skills - it significantly improves the quality of the responses!
| | Parameter | Default | Description | | ||
| |-----------|---------|-------------| | ||
| | `enable_mcp_agents` | `false` | Enable or disable the `/api/mcp/agents` endpoint. | | ||
| | `enable_mcp_agents_query_tool` | `false` | Show or hide the `query` tool on the agents endpoint. | |
There was a problem hiding this comment.
I think this should either be enabled by default, or left undocumented. Let's not make this another flag that users have to configure.
| | Parameter | Default | Description | | ||
| |-----------|---------|-------------| | ||
| | `enable_mcp_agents` | `false` | Enable or disable the `/api/mcp/agents` endpoint. | | ||
| | `enable_mcp_agents_query_tool` | `false` | Show or hide the `query` tool on the agents endpoint. | |
There was a problem hiding this comment.
Same as above: I think this should either be enabled by default, or left undocumented. Let's not make this another flag that users have to configure.
As discussed internally. Fixes https://linear.app/materializeinc/issue/DEX-22/rename-mcp-observatory-endpoint-to-developer Docs PR has been updated as well: #35604 @jubrad I might need a hand in renaming the LD flag for this once it lands.
|
|
||
| {{< /tabs >}} | ||
|
|
||
| ## What you can ask |
There was a problem hiding this comment.
Minor comment: can we make this the overview? It really speaks to the value of the feature, and I think it is better than what we have in the Overview section today!
5 participants
Initial draft of the built-in MCP server documentation.
Fixes https://linear.app/materializeinc/issue/DEX-6/mcp-user-documentation