Skip to content

The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.

docs: add fx as a supported MCP client (#49446)

Esteban Suárezadffb2661332
diff --git a/packages/ui-patterns/src/McpUrlBuilder/assets/fx-icon-dark.svg b/packages/ui-patterns/src/McpUrlBuilder/assets/fx-icon-dark.svg
new file mode 100644
index 00000000000..30687856348
--- /dev/null
+++ b/packages/ui-patterns/src/McpUrlBuilder/assets/fx-icon-dark.svg
@@ -0,0 +1,3 @@
+<svg width="156" height="156" viewBox="166.241 0 155.861 155.75" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M237.892 0C243.178 8.73262e-05 249.383 1.41857 253.025 3.07422L255.093 4.01367L250.076 18.6299L247.677 17.7461C244.901 16.7234 241.938 15.7998 238.491 15.7998C234.984 15.7998 232.787 16.5601 231.08 18.3213C229.231 20.2297 227.629 23.6395 226.229 29.7578L226.227 29.7617L226.228 29.7627L225.136 34.8506H241.669L260.432 34.9502L260.694 34.9512L260.842 35.1689L278.854 61.6328L296.736 34.9502H320.866L291.676 76.7402L322.102 119.75H299.331L299.182 119.546L241.144 40.4775L239.35 49.4004H222.069L205.688 127.208C203.927 135.709 201.185 142.838 196.777 147.866C192.27 153.008 186.201 155.75 178.342 155.75C174.181 155.75 170.746 155.109 167.909 154.107L166.241 153.519V137.182L166.899 137.4L169.531 138.278C172.182 139.162 174.414 139.8 177.142 139.8C178.528 139.8 179.703 139.526 180.732 138.98C181.764 138.434 182.677 137.6 183.52 136.442C185.304 133.989 186.716 130.135 187.897 124.672L203.76 49.4004H189.874L191.759 39.4375L192.039 39.3457L206.818 34.4668L208.154 28.6416C210.516 18.2065 213.772 10.9381 218.708 6.31836C223.737 1.61217 230.127 3.08752e-05 237.892 0ZM273.987 99.084L260.073 120.25H234.541L261.003 82.0215L273.987 99.084Z" fill="#F1ECEC"/>
+</svg>
diff --git a/packages/ui-patterns/src/McpUrlBuilder/assets/fx-icon.svg b/packages/ui-patterns/src/McpUrlBuilder/assets/fx-icon.svg
new file mode 100644
index 00000000000..a630d4386d6
--- /dev/null
+++ b/packages/ui-patterns/src/McpUrlBuilder/assets/fx-icon.svg
@@ -0,0 +1,3 @@
+<svg width="156" height="156" viewBox="166.241 0 155.861 155.75" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M237.892 0C243.178 8.73262e-05 249.383 1.41857 253.025 3.07422L255.093 4.01367L250.076 18.6299L247.677 17.7461C244.901 16.7234 241.938 15.7998 238.491 15.7998C234.984 15.7998 232.787 16.5601 231.08 18.3213C229.231 20.2297 227.629 23.6395 226.229 29.7578L226.227 29.7617L226.228 29.7627L225.136 34.8506H241.669L260.432 34.9502L260.694 34.9512L260.842 35.1689L278.854 61.6328L296.736 34.9502H320.866L291.676 76.7402L322.102 119.75H299.331L299.182 119.546L241.144 40.4775L239.35 49.4004H222.069L205.688 127.208C203.927 135.709 201.185 142.838 196.777 147.866C192.27 153.008 186.201 155.75 178.342 155.75C174.181 155.75 170.746 155.109 167.909 154.107L166.241 153.519V137.182L166.899 137.4L169.531 138.278C172.182 139.162 174.414 139.8 177.142 139.8C178.528 139.8 179.703 139.526 180.732 138.98C181.764 138.434 182.677 137.6 183.52 136.442C185.304 133.989 186.716 130.135 187.897 124.672L203.76 49.4004H189.874L191.759 39.4375L192.039 39.3457L206.818 34.4668L208.154 28.6416C210.516 18.2065 213.772 10.9381 218.708 6.31836C223.737 1.61217 230.127 3.08752e-05 237.892 0ZM273.987 99.084L260.073 120.25H234.541L261.003 82.0215L273.987 99.084Z" fill="#211E1E"/>
+</svg>
diff --git a/packages/ui-patterns/src/McpUrlBuilder/clients.data.ts b/packages/ui-patterns/src/McpUrlBuilder/clients.data.ts
index 972815f37b5..c73510e5023 100644
--- a/packages/ui-patterns/src/McpUrlBuilder/clients.data.ts
+++ b/packages/ui-patterns/src/McpUrlBuilder/clients.data.ts
@@ -4,6 +4,7 @@ import type {
CodexMcpConfig,
CopilotMcpConfig,
FactoryMcpConfig,
+ FxMcpConfig,
GeminiMcpConfig,
GooseMcpConfig,
GrokMcpConfig,
@@ -341,6 +342,24 @@ export const MCP_CLIENT_DATA: McpClientData[] = [
}
},
},
+ {
+ key: 'fx',
+ label: 'fx',
+ icon: 'fx',
+ hasDistinctDarkIcon: true,
+ configFile: '~/.fx/mcp.json',
+ externalDocsUrl: 'https://fx.sh/docs/capabilities/mcp',
+ transformConfig: (config): FxMcpConfig => {
+ return {
+ mcp: {
+ supabase: {
+ type: 'http',
+ url: config.mcpServers.supabase.url,
+ },
+ },
+ }
+ },
+ },
{
key: 'kiro',
label: 'Kiro',
@@ -413,12 +432,24 @@ export const MCP_CLI_COMMANDS: Record<string, McpCliCommands> = {
opencode: {
authenticate: 'opencode mcp auth supabase',
},
+ fx: {
+ authenticate: '/mcp auth supabase --open',
+ },
}
export const MCP_CLIENT_GROUPS = [
{
heading: 'AI Agent CLI',
- keys: ['claude-code', 'codex', 'grok', 'gemini-cli', 'copilot-cli', 'opencode', 'factory'],
+ keys: [
+ 'claude-code',
+ 'codex',
+ 'grok',
+ 'gemini-cli',
+ 'copilot-cli',
+ 'opencode',
+ 'factory',
+ 'fx',
+ ],
},
{
heading: 'Web Clients',
diff --git a/packages/ui-patterns/src/McpUrlBuilder/clients.instructions.md.tsx b/packages/ui-patterns/src/McpUrlBuilder/clients.instructions.md.tsx
index f45aa6bedcd..77ac73995d7 100644
--- a/packages/ui-patterns/src/McpUrlBuilder/clients.instructions.md.tsx
+++ b/packages/ui-patterns/src/McpUrlBuilder/clients.instructions.md.tsx
@@ -254,6 +254,27 @@ export const MCP_CLIENT_INSTRUCTIONS: Record<string, McpClientInstructions> = {
</>
),
},
+ fx: {
+ alternate: () => (
+ <>
+ <paragraph>
+ fx reads MCP servers only from this profile, so a file inside a repository cannot add one.
+ If a session is already open, apply the change with <inlineCode value="/mcp reload" />.
+ </paragraph>
+ <paragraph>
+ Then authenticate from the fx shell. This opens your browser to complete the OAuth flow:
+ </paragraph>
+ <code lang="bash" value={MCP_CLI_COMMANDS['fx'].authenticate!} />
+ <paragraph>
+ Confirm the server is connected with <inlineCode value="/mcp list" />.
+ </paragraph>
+ <paragraph>
+ For more details, see{' '}
+ <link url="https://fx.sh/docs/capabilities/mcp">MCP configuration</link> in fx.
+ </paragraph>
+ </>
+ ),
+ },
kiro: {
deepLinkDescription: (
<paragraph>
diff --git a/packages/ui-patterns/src/McpUrlBuilder/types.test.ts b/packages/ui-patterns/src/McpUrlBuilder/types.test.ts
new file mode 100644
index 00000000000..e7e8183b555
--- /dev/null
+++ b/packages/ui-patterns/src/McpUrlBuilder/types.test.ts
@@ -0,0 +1,26 @@
+import { describe, expect, it } from 'vitest'
+
+import { MCP_CLIENT_DATA } from './clients.data'
+import { getMcpUrl, type McpClientBaseConfig } from './types'
+
+const SERVER_URL = 'https://mcp.supabase.com/mcp?project_ref=abc123&read_only=true'
+
+/**
+ * `windsurf` configures a stdio `mcp-remote` command that carries the URL in `args`, so its
+ * config has no URL field to read back. It renders no instructions and no deep link, so it
+ * never reaches `getMcpUrl`.
+ */
+const CLIENTS_WITHOUT_URL_IN_CONFIG = new Set(['windsurf'])
+
+describe('getMcpUrl', () => {
+ it.each(
+ MCP_CLIENT_DATA.filter((client) => !CLIENTS_WITHOUT_URL_IN_CONFIG.has(client.key)).map(
+ (client) => [client.key, client] as const
+ )
+ )('reads the server URL back out of the %s config', (_key, client) => {
+ const base: McpClientBaseConfig = { mcpServers: { supabase: { url: SERVER_URL } } }
+ const config = client.transformConfig ? client.transformConfig(base) : base
+
+ expect(getMcpUrl(config)).toBe(SERVER_URL)
+ })
+})
diff --git a/packages/ui-patterns/src/McpUrlBuilder/types.ts b/packages/ui-patterns/src/McpUrlBuilder/types.ts
index f1bdc14acc3..570d09de794 100644
--- a/packages/ui-patterns/src/McpUrlBuilder/types.ts
+++ b/packages/ui-patterns/src/McpUrlBuilder/types.ts
@@ -171,6 +171,20 @@ export interface OpenCodeMcpConfig {
}
}
+/**
+ * Configuration format for the fx MCP client.
+ * fx also keys servers under `mcp`, but reads them from its own profile
+ * (`~/.fx/mcp.json`) and names the transport `http` rather than `remote`.
+ */
+export interface FxMcpConfig {
+ mcp: {
+ supabase: {
+ type: 'http'
+ url: string
+ }
+ }
+}
+
export interface AntigravityMcpConfig {
mcpServers: {
supabase: {
@@ -210,6 +224,7 @@ export type McpClientConfig =
| CodexMcpConfig
| CursorMcpConfig
| FactoryMcpConfig
+ | FxMcpConfig
| GeminiMcpConfig
| GooseMcpConfig
| GrokMcpConfig
@@ -245,6 +260,10 @@ export function isOpenCodeMcpConfig(config: McpClientConfig): config is OpenCode
return '$schema' in config && 'mcp' in config && 'supabase' in config.mcp
}
+export function isFxMcpConfig(config: McpClientConfig): config is FxMcpConfig {
+ return 'mcp' in config && 'supabase' in config.mcp && config.mcp.supabase.type === 'http'
+}
+
export function isAntigravityMcpConfig(config: McpClientConfig): config is AntigravityMcpConfig {
return (
'mcpServers' in config &&
@@ -276,6 +295,9 @@ export function getMcpUrl(config: McpClientConfig): string {
if (isOpenCodeMcpConfig(config)) {
return config.mcp.supabase.url
}
+ if (isFxMcpConfig(config)) {
+ return config.mcp.supabase.url
+ }
if (isAntigravityMcpConfig(config)) {
return config.mcpServers.supabase.serverUrl
}
diff --git a/packages/ui-patterns/src/McpUrlBuilder/utils/getMcpIconSrc.test.ts b/packages/ui-patterns/src/McpUrlBuilder/utils/getMcpIconSrc.test.ts
index c1ecc2a3560..afa7993b6b4 100644
--- a/packages/ui-patterns/src/McpUrlBuilder/utils/getMcpIconSrc.test.ts
+++ b/packages/ui-patterns/src/McpUrlBuilder/utils/getMcpIconSrc.test.ts
@@ -49,6 +49,22 @@ describe('getMcpClientIconSrc', () => {
expect(darkSrc).not.toBe(lightSrc)
})
+ it('returns the dark icon for fx when requested as a distinct variant', () => {
+ const lightSrc = getMcpClientIconSrc({
+ icon: 'fx',
+ useDarkVariant: false,
+ hasDistinctDarkIcon: true,
+ })
+ const darkSrc = getMcpClientIconSrc({
+ icon: 'fx',
+ useDarkVariant: true,
+ hasDistinctDarkIcon: true,
+ })
+
+ expect(darkSrc).toBeTruthy()
+ expect(darkSrc).not.toBe(lightSrc)
+ })
+
it('falls back to the default icon when no distinct dark variant should be used', () => {
const lightSrc = getMcpClientIconSrc({
icon: 'factory',
diff --git a/packages/ui-patterns/src/McpUrlBuilder/utils/mcpIconAssets.ts b/packages/ui-patterns/src/McpUrlBuilder/utils/mcpIconAssets.ts
index 7795c45bd6a..a5fe3f63eb6 100644
--- a/packages/ui-patterns/src/McpUrlBuilder/utils/mcpIconAssets.ts
+++ b/packages/ui-patterns/src/McpUrlBuilder/utils/mcpIconAssets.ts
@@ -10,6 +10,8 @@ import devinDarkIcon from '../assets/devin-icon-dark.svg'
import devinIcon from '../assets/devin-icon.svg'
import factoryDarkIcon from '../assets/factory-icon-dark.svg'
import factoryIcon from '../assets/factory-icon.svg'
+import fxDarkIcon from '../assets/fx-icon-dark.svg'
+import fxIcon from '../assets/fx-icon.svg'
import geminiCliIcon from '../assets/gemini-cli-icon.svg'
import gooseDarkIcon from '../assets/goose-icon-dark.svg'
import gooseIcon from '../assets/goose-icon.svg'
@@ -44,6 +46,7 @@ const MCP_CLIENT_ICON_ASSETS = {
cursor: { light: cursorIcon, dark: cursorDarkIcon },
devin: { light: devinIcon, dark: devinDarkIcon },
factory: { light: factoryIcon, dark: factoryDarkIcon },
+ fx: { light: fxIcon, dark: fxDarkIcon },
'gemini-cli': { light: geminiCliIcon, dark: geminiCliIcon },
goose: { light: gooseIcon, dark: gooseDarkIcon },
grok: { light: grokIcon, dark: grokDarkIcon },