docs: initial draft of built-in MCP server integration page#35604
docs: initial draft of built-in MCP server integration page#35604kay-kim merged 14 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
|
|
||
| ## 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!
| 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
| * **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?
| 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.
|
|
||
| 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.
| '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).
| 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 ..."
| 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.
| | **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 |
| '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).
| | 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!
|
@maheshwarip all comments should be addressed except two that need product decisions:
Everything else is in. Ready for re-review when those two are settled. Thanks @kay-kim for helping out here 🙇 |
maheshwarip
dismissed
their stale review
un-checking myself here - will let Kay review this!
We are going to launch with the feature on by default @bobbyiliev . I'd use the public preview note in the docs, and keep the docs heading as "Disabling the endpoint" |
|
|
||
| Materialize provides a built-in [Model Context Protocol | ||
| (MCP)](https://modelcontextprotocol.io/) endpoint for troubleshooting and | ||
| observability. Connect an MCP-compatible AI agent (such as Claude Code, Claude |
There was a problem hiding this comment.
So ... I would change the "Connect ..." to "You can connect ..." and move it to the end of the Overview section ... so that it flows naturally into the ## Connect section
There was a problem hiding this comment.
Good point! Just updated this!
There was a problem hiding this comment.
Oh .. heh .. I meant the table too 😄 as it goes with that sentence.
As discussed here: #35604 (comment)
| observability. The MCP interface is served directly by the database; no sidecar | ||
| process or external server is required. | ||
|
|
||
| | Question | What the agent does | |
There was a problem hiding this comment.
this table should also go below as well
As discussed here: #35604 (comment)
5 participants
Initial draft of the built-in MCP server documentation.
Fixes https://linear.app/materializeinc/issue/DEX-6/mcp-user-documentation