console: MCP Server connection instructions in the console by leedqin · Pull Request #35902 · MaterializeInc/materialize

leedqin · 2026-04-07T21:19:34Z

Motivation

Adding MCP connection instructions in the console. Linear Issue CNS-45:

Description

Added MCP connect tab for the connect modal. Tested it on various auth modes:
Cloud

OIDC

password

Verification

How do you know this change is correct? Describe new or existing automated
tests, or manual steps you took.

github-actions · 2026-04-07T21:19:45Z

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).

jubrad

If MCP is not enabled by default should we not show these by default, or at least add a disclaimer about how to enable or to contact support to enable?

jubrad · 2026-04-08T15:47:12Z

                          lineHeight="1.15"
                        >
-                          Service
+                          Services and agents


If this is a title both should be capitalized

Services and Agents

jubrad · 2026-04-08T15:48:33Z

-            after you reload!
+          <Text pt={2} textStyle="text-base" color={colors.foreground.primary}>
+            Write this down; you will not be able to see your app password or
+            token again after you reload!


token again after you reload

I believe this is just after you close this modal, but this is probably fine.

jubrad · 2026-04-08T15:58:16Z

        >
-          Copy this app password to somewhere safe. App passwords cannot be
-          displayed after initial creation.
+          Copy these to somewhere safe. They cannot be displayed after initial


Either way what we're displaying is an app password, just formatting changes
I think we're ok with

Copy this somewhere safe. App passwords cannot be displayed after initial creation.

jubrad · 2026-04-08T15:58:36Z

+
+const mcpConfigJson = (
+  baseUrl: string,
+  endpoint: "agents" | "observatory",


This name might be changing to developer along with the endpoint

leedqin · 2026-04-08T20:55:24Z

Resolved some feedback from Slack and edits here in the latest commit

jubrad

I actually think this is pretty unintuitive... you click click "create app password" at the bottom of the modal and the thing that gets added there is the app_password, but the mcp token gets added to the instructions and it's very easy to miss.

I think there's a more serious error around service accounts not being handled correctly.

jubrad · 2026-04-09T04:17:24Z

+  );
+};
+
+export default McpConnectModal;


What uses this export?

jubrad · 2026-04-09T04:27:42Z

 }: SecretBoxProps) => {
  const { colors } = useTheme<MaterializeTheme>();
+
+  const base64Token = btoa(`${userEmail}:${password}`);


I think btoa is just ascii, and we'd definitely let unicode service_names. I attempted to this, in preview using a service account, but the code used the user email in for an app password created with a service account which won't work.

jubrad · 2026-04-09T04:35:31Z

Sorry about the accidental close, hit the wrong button.

kay-kim · 2026-04-09T16:18:32Z

+        overflow="visible"
+        message={
+          isCloud
+            ? "The MCP server is not enabled by default. Contact Materialize support to enable the MCP endpoints for your environment."


If launching in Public Preview (https://materializeinc.slack.com/archives/C09ERRA0YAK/p1775590203042079) ... will it not be enabled by default?

For some self managed customers, they might still need to enable it via mz_system

Depending on the answer to your question https://materializeinc.slack.com/archives/C09ERRA0YAK/p1775773024131799?thread_ts=1775758256.275809&cid=C09ERRA0YAK ... possibly may need to change.

kay-kim · 2026-04-09T16:25:22Z

+
+      <VStack alignItems="stretch" spacing="2">
+        <Text textStyle="heading-xs">Step 2. Connect your client</Text>
+        <Text fontSize="sm" color={colors.foreground.secondary}>


I'm wondering ... would having a radio button group that specifies

Agent endpoint

Developer endpoint
be easier for our users to copy/paste?

That way, we don't need to have https://github.com/MaterializeInc/materialize/pull/35902/changes#diff-96cf50a06807c795164be7144f6cd56d25db3eedf76ed6bfb298610d50679e56R179-R186
?

Good point! added that

kay-kim · 2026-04-09T16:29:04Z

+        <Text textStyle="heading-xs">Step 1. Get your Base64 token</Text>
+        <Text fontSize="sm" color={colors.foreground.secondary}>
+          {isCloud
+            ? "Create an app password (under Account > App Passwords), then run the following in your terminal:"


Given that the modal actually has the common create app password button which now creates the app password and token, do we need the "Create an app password (under Account > App Password), then" ?

I think we can do both. For future purposes; especially for service accounts they would need to go through the Account > App Password flow

kay-kim · 2026-04-09T16:33:52Z

+        <Text fontSize="sm" color={colors.foreground.secondary}>
+          {isCloud
+            ? "Create an app password (under Account > App Passwords), then run the following in your terminal:"
+            : "Use a SQL role with LOGIN and PASSWORD privileges. Run the following in your terminal:"}


The SQL role with LOGIN and PASSWORD privileges ... not quite privileges ...
I see in the docs "Create roles with login/password/superuser privileges (Self-Managed only)." ... the privileges was only for the superuser part.

I would probably go "Use a login role with password attribute" or "Use a role with login and password attributes" or something.

kay-kim · 2026-04-09T19:11:00Z

+            },
+            {
+              title: "Claude Desktop",
+              contents: mcpConfigJson(baseUrl, endpoint),


We don't tell where to save this content.

Added this here in the last commit

kay-kim · 2026-04-09T19:11:24Z

+            },
+            {
+              title: "Cursor",
+              contents: mcpConfigJson(baseUrl, endpoint),


kay-kim · 2026-04-10T17:24:10Z

+            <Radio value="agents" size="sm">
+              Agents
+            </Radio>


So ... per https://materializeinc.slack.com/archives/C09ERRA0YAK/p1775758256275809 ... we probably want to hide the agents for now?

kay-kim · 2026-04-10T17:25:12Z

+        overflow="visible"
+        message={
+          isCloud
+            ? "The MCP server is not enabled by default. Contact Materialize support to enable the MCP endpoints for your environment."


Depending on the answer to your question https://materializeinc.slack.com/archives/C09ERRA0YAK/p1775773024131799?thread_ts=1775758256.275809&cid=C09ERRA0YAK ... possibly may need to change.

kay-kim · 2026-04-10T17:26:57Z

+  const [currentEnvironment] = useAtom(currentEnvironmentState);
+  const appConfig = useAppConfig();
+  const isCloud = appConfig.mode === "cloud";
+  const [endpoint, setEndpoint] = useState<"agents" | "developer">("agents");


maybe need to default to developer per the release schedule?

(also heads up on the agents endpoint: #35930)

kay-kim

left a minor comment.

kay-kim · 2026-04-16T13:18:55Z

+  mcpBase64Token,
+  ...props
+}: McpConnectInstructionsProps) => {
+  const { colors } = useTheme<MaterializeTheme>();


Something to consider for the future (since the docs for MCP aren't published yet):

In https://github.com/MaterializeInc/materialize/pull/35902/changes#diff-0186f9eab0349780bb63a74a9a9e5a60fbba30089003fd88a0b9f3099ded0910R84-R92, we link people to integrations/sql-clients.

We might want to in the Mcp ConnectInstructions include a link to /docs/integrations/mcp-server/ as well.

Refactor AppPasswordsPage and ConnectModal for consistency; update McpConnectInstructions layout - Changed "Services and agents" to "Service" for clarity in AppPasswordsPage. - Updated helper text to reflect the singular "Service" in AppPasswordsPage. - Added overflow and minWidth properties to SecretBox components in both AppPasswordsPage and ConnectModal for better UI handling. - Improved layout in McpConnectInstructions by consolidating code blocks and enhancing descriptions for clarity. Enhance MCP token handling and UI updates across components - Added support for pre-computed Base64 MCP tokens in ConnectInstructions and McpConnectInstructions. - Updated ConnectModal to pass the MCP token to relevant components. - Improved layout and descriptions in AppPasswordsPage and McpConnectInstructions for better clarity and user experience. - Adjusted text prompts to emphasize the importance of saving credentials after creation. Fix MCP token encoding and service account handling; - Use unicode-safe base64 encoding (TextEncoder) instead of btoa, which fails on non-ASCII service account names - Use the service account user instead of the logged-in user's email when generating MCP tokens for service account app passwords - Show MCP token under app password only when MCP Server tab is active - Add Agents/Developer radio group to MCP instructions so users can switch endpoints without a separate observatory section - Rename observatory endpoint references to developer (per MaterializeInc#35918) - Add -w0 flag to base64 command for Linux compatibility small cleanups letting the user know where to save the mcp config Removing disclaimer and radio button for "Agents"

### Motivation Adding MCP connection instructions in the console. Linear Issue [CNS-45](https://linear.app/materializeinc/issue/CNS-45/add-mcp-connection-instructions-in-the-console): ### Description Added MCP connect tab for the connect modal. Tested it on various auth modes: **Cloud** <img width="2654" height="2032" alt="image" src="https://github.com/user-attachments/assets/80ab2593-c017-49ff-aec0-24f9303485d0" /> **OIDC** <img width="2970" height="2016" alt="image" src="https://github.com/user-attachments/assets/ea61fac7-f393-4787-9a9c-c337f35e6106" /> **password** <img width="2850" height="1990" alt="image" src="https://github.com/user-attachments/assets/be494be0-6ec2-4346-a237-9eb60c659c34" /> ### Verification How do you know this change is correct? Describe new or existing automated tests, or manual steps you took.

leedqin requested a review from a team as a code owner April 7, 2026 21:19

leedqin requested review from SangJunBak and removed request for a team April 7, 2026 21:19

kay-kim mentioned this pull request Apr 7, 2026

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

Merged

leedqin added the A-CONSOLE Area: Console label Apr 7, 2026

leedqin changed the title ~~MCP Server connection instructions in the console~~ console: MCP Server connection instructions in the console Apr 7, 2026

leedqin requested review from bobbyiliev and jubrad April 8, 2026 14:46

jubrad reviewed Apr 8, 2026

View reviewed changes

jubrad requested changes Apr 9, 2026

View reviewed changes

jubrad closed this Apr 9, 2026

jubrad reopened this Apr 9, 2026

kay-kim reviewed Apr 9, 2026

View reviewed changes

leedqin force-pushed the console-mcp-connectivity branch from cb7cb16 to a3f2ff0 Compare April 9, 2026 18:20

leedqin requested review from jubrad and kay-kim April 9, 2026 18:20

kay-kim reviewed Apr 9, 2026

View reviewed changes

jubrad approved these changes Apr 10, 2026

View reviewed changes

leedqin requested a review from kay-kim April 10, 2026 17:08

kay-kim reviewed Apr 10, 2026

View reviewed changes

leedqin force-pushed the console-mcp-connectivity branch from fc3bdfe to b51903b Compare April 16, 2026 13:01

kay-kim approved these changes Apr 16, 2026

View reviewed changes

leedqin force-pushed the console-mcp-connectivity branch from b51903b to 2cc88d1 Compare April 17, 2026 14:52

leedqin enabled auto-merge (squash) April 17, 2026 14:54

leedqin force-pushed the console-mcp-connectivity branch from 2cc88d1 to aff0522 Compare April 17, 2026 15:10

leedqin merged commit 9de10e7 into MaterializeInc:main Apr 17, 2026
112 checks passed

Conversation

leedqin commented Apr 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation

Description

Verification

Uh oh!

github-actions bot commented Apr 7, 2026

PR title guidelines

Pre-merge checklist

Uh oh!

jubrad left a comment

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!

leedqin commented Apr 8, 2026

Uh oh!

jubrad left a comment

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!

jubrad commented Apr 9, 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

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!

kay-kim left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

leedqin commented Apr 7, 2026 •

edited

Loading