Skip to content

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

refactor(studio): add remote tool contracts, starting with list_extensions (#52175)

Charis23a56b2e6007
diff --git a/apps/studio/lib/ai/README.md b/apps/studio/lib/ai/README.md
index 4f8ec1f6e22..8eb8f9cfd4a 100644
--- a/apps/studio/lib/ai/README.md
+++ b/apps/studio/lib/ai/README.md
@@ -62,23 +62,23 @@ Keep per-request context in `assistant-context.ts`. The shared system prompt is
### Tools
-| Change | Start here |
-| ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Tool assembly and platform/self-hosted selection | [tools/index.ts](./tools/index.ts) |
-| Allowlist, minimum opt-in levels, and blocked-tool responses | [tool-filter.ts](./tool-filter.ts) |
-| Studio tool assembly and opt-in requests | [studio-tools.ts](./tools/studio-tools.ts) |
-| Remote MCP connection and tool selection | [supabase-mcp.ts](./supabase-mcp.ts), [mcp-tools.ts](./tools/mcp-tools.ts) |
-| Schema and policy tools | [schema-tools.ts](./tools/schema-tools.ts) |
-| Reports, notebooks, incidents, and support | [report-tools.ts](./tools/report-tools.ts), [notebook-tools.ts](./tools/notebook-tools.ts), [incident-tools.ts](./tools/incident-tools.ts), [support-tools.ts](./tools/support-tools.ts) |
-| Self-hosted tools | [fallback-tools.ts](./tools/fallback-tools.ts) |
-| Contract-based tools (see [Tool contracts](#tool-contracts)) | [registry.ts](./tools/registry.ts) lists them in `TOOL_CONTRACTS`; [types.ts](./tools/types.ts), [tool-from-contract.ts](./tools/tool-from-contract.ts) |
-
-Tools are moving to [contracts](#tool-contracts); the rest declare their schemas and output handling directly. [registry.ts](./tools/registry.ts) is the source of truth for which are which: a tool in `TOOL_CONTRACTS` is a contract tool.
+| Change | Start here |
+| ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Tool assembly and platform/self-hosted selection | [tools/index.ts](./tools/index.ts) |
+| Allowlist, minimum opt-in levels, and blocked-tool responses | [tool-filter.ts](./tool-filter.ts) |
+| Studio tool assembly and opt-in requests | [studio-tools.ts](./tools/studio-tools.ts) |
+| Remote MCP connection and tool selection | [supabase-mcp.ts](./supabase-mcp.ts), [mcp-tools.ts](./tools/mcp-tools.ts) |
+| Schema and policy tools | [schema-tools.ts](./tools/schema-tools.ts) |
+| Reports, notebooks, incidents, and support | [report-tools.ts](./tools/report-tools.ts), [notebook-tools.ts](./tools/notebook-tools.ts), [incident-tools.ts](./tools/incident-tools.ts), [support-tools.ts](./tools/support-tools.ts) |
+| Self-hosted tools | [fallback-tools.ts](./tools/fallback-tools.ts) |
+| Contract-based tools (see [Tool contracts](#tool-contracts)) | [registry.ts](./tools/registry.ts) lists them in `TOOL_CONTRACTS` (and remote MCP tools in `REMOTE_TOOL_CONTRACTS`); [types.ts](./tools/types.ts), [tool-from-contract.ts](./tools/tool-from-contract.ts) |
+
+Tools are moving to [contracts](#tool-contracts); the rest declare their schemas and output handling directly. [registry.ts](./tools/registry.ts) is the source of truth for which are which: a tool in `TOOL_CONTRACTS` or `REMOTE_TOOL_CONTRACTS` is a contract tool.
For a new or changed tool:
1. Prefer a [contract](#tool-contracts) for a new tool. Otherwise implement it in the appropriate tool module.
-2. Include it in `getTools` through the module's tool getter, and add its name to the allowlist in `tool-filter.ts`. A contract declares minimum access as `minOptInLevel`; other tools use `TOOL_CATEGORY_MAP`.
+2. Include it in `getTools` through the module's tool getter, and add its name to the allowlist in `tool-filter.ts`. A contract, local or remote, declares minimum access as `minOptInLevel`; other tools use `TOOL_CATEGORY_MAP`.
3. Decide whether execution needs user approval and what output may reach the model, including on history replay. Read the [SQL safety skill](../../../../.agents/skills/safe-sql-execution/SKILL.md) before changing SQL execution.
4. Update `Message.Parts.tsx` and its helpers if the tool needs a UI renderer.
5. Update relevant tests, mock tools, and evaluation cases. See [local development and validation](#local-development-and-validation).
@@ -106,6 +106,10 @@ To migrate a tool to a contract:
7. Test the contract's `toModelOutput` at every opt-in level and on history replay, in [registry.test.ts](./tools/registry.test.ts) and [tool-sanitizer.test.ts](./tools/tool-sanitizer.test.ts) as applicable.
8. Call out any change to what the model sees or to the stored shape in the PR description.
+#### Remote contracts
+
+A tool the remote MCP server implements has a `RemoteToolContract`: only `name`, `minOptInLevel`, and `needsApproval`. The server owns the description, input schema, execution, and output, so there is no `.server.ts` file and its parts stay `dynamic-tool`, outside `StudioUIMessage`. Register it in `REMOTE_TOOL_CONTRACTS` and remove it from `TOOL_CATEGORY_MAP`; [mcp-tools.ts](./tools/mcp-tools.ts) applies `needsApproval`, since MCP tool definitions can't declare it. [list-extensions.ts](./tools/list-extensions.ts) is an example.
+
## Access and data sharing
These checks have different responsibilities:
diff --git a/apps/studio/lib/ai/tool-filter.ts b/apps/studio/lib/ai/tool-filter.ts
index eb6a292afd1..b2b02c078fd 100644
--- a/apps/studio/lib/ai/tool-filter.ts
+++ b/apps/studio/lib/ai/tool-filter.ts
@@ -2,7 +2,12 @@ import type { Tool, ToolSet } from 'ai'
import { z } from 'zod'
import { isOptInLevelAtLeast } from './opt-in-level'
-import { getToolContract, type ContractToolName } from './tools/registry'
+import {
+ getRemoteToolContract,
+ getToolContract,
+ type ContractToolName,
+ type RemoteContractToolName,
+} from './tools/registry'
import type { AiOptInLevel } from '@/hooks/misc/useOrgOptedIntoAi'
// Add the DatabaseExtension type import
@@ -79,15 +84,18 @@ type ToolCategory = (typeof TOOL_CATEGORIES)[keyof typeof TOOL_CATEGORIES]
/**
* Mapping of tool names to their categories. Tools that have migrated to a contract
- * (`TOOL_CONTRACTS`) declare their own `minOptInLevel` instead and aren't listed here.
+ * (`TOOL_CONTRACTS` or `REMOTE_TOOL_CONTRACTS`) declare their own `minOptInLevel` instead and
+ * aren't listed here.
*/
-export const TOOL_CATEGORY_MAP: Record<Exclude<ToolName, ContractToolName>, ToolCategory> = {
+export const TOOL_CATEGORY_MAP: Record<
+ Exclude<ToolName, ContractToolName | RemoteContractToolName>,
+ ToolCategory
+> = {
// UI tools - always available
search_docs: TOOL_CATEGORIES.UI,
// Schema tools - MCP
list_tables: TOOL_CATEGORIES.SCHEMA,
- list_extensions: TOOL_CATEGORIES.SCHEMA,
list_edge_functions: TOOL_CATEGORIES.SCHEMA,
list_branches: TOOL_CATEGORIES.SCHEMA,
getSchemaTables: TOOL_CATEGORIES.SCHEMA,
@@ -127,7 +135,7 @@ function isCategorizedTool(name: string): name is keyof typeof TOOL_CATEGORY_MAP
* tool isn't on the allowlist. A contract's `minOptInLevel` wins over the category map.
*/
function getToolMinimumLevel(toolName: string): AiOptInLevel | null | undefined {
- const contract = getToolContract(toolName)
+ const contract = getToolContract(toolName) ?? getRemoteToolContract(toolName)
if (contract) return contract.minOptInLevel
if (isCategorizedTool(toolName)) return getMinimumOptInLevel(TOOL_CATEGORY_MAP[toolName])
return undefined
diff --git a/apps/studio/lib/ai/tools/list-extensions.ts b/apps/studio/lib/ai/tools/list-extensions.ts
new file mode 100644
index 00000000000..7abeceb8acd
--- /dev/null
+++ b/apps/studio/lib/ai/tools/list-extensions.ts
@@ -0,0 +1,7 @@
+import type { RemoteToolContract } from './types'
+
+export const contract = {
+ name: 'list_extensions',
+ minOptInLevel: 'schema',
+ needsApproval: false,
+} as const satisfies RemoteToolContract
diff --git a/apps/studio/lib/ai/tools/mcp-tools.test.ts b/apps/studio/lib/ai/tools/mcp-tools.test.ts
index 349c642c71a..3cdc208cf7c 100644
--- a/apps/studio/lib/ai/tools/mcp-tools.test.ts
+++ b/apps/studio/lib/ai/tools/mcp-tools.test.ts
@@ -53,6 +53,12 @@ describe('ai/tools/mcp-tools getMcpTools', () => {
expect(result).not.toHaveProperty('deploy_edge_function')
})
+ it('takes needsApproval from the contract', async () => {
+ const result = await getMcpTools(BASE_PARAMS)
+
+ expect(result.list_extensions?.needsApproval).toBe(false)
+ })
+
it('warns when the remote server is missing an expected tool (contract drift)', async () => {
const { list_branches, ...withoutBranches } = FULL_REMOTE_TOOLS
tools.mockResolvedValueOnce(withoutBranches)
diff --git a/apps/studio/lib/ai/tools/mcp-tools.ts b/apps/studio/lib/ai/tools/mcp-tools.ts
index d14043528a7..9d4ff58892b 100644
--- a/apps/studio/lib/ai/tools/mcp-tools.ts
+++ b/apps/studio/lib/ai/tools/mcp-tools.ts
@@ -4,6 +4,7 @@ import type { ToolSet } from 'ai'
import { createSupabaseMCPClient } from '../supabase-mcp'
import { filterToolsByOptInLevel, toolSetValidationSchema } from '../tool-filter'
+import { REMOTE_TOOL_CONTRACTS } from './registry'
import type { AiOptInLevel } from '@/hooks/misc/useOrgOptedIntoAi'
/**
@@ -78,7 +79,15 @@ export const getMcpTools = async ({
signal.addEventListener('abort', closeClient, { once: true })
try {
- const availableMcpTools = (await mcpClient.tools()) as ToolSet
+ const remoteTools = (await mcpClient.tools()) as ToolSet
+
+ const availableMcpTools: ToolSet = { ...remoteTools }
+ for (const contract of Object.values(REMOTE_TOOL_CONTRACTS)) {
+ const remoteTool = remoteTools[contract.name]
+ if (remoteTool) {
+ availableMcpTools[contract.name] = { ...remoteTool, needsApproval: contract.needsApproval }
+ }
+ }
// Runtime drift detection: `EXPECTED_MCP_TOOLS` is compile-time-checked
// against the pinned package (see its declaration), but the *deployed* remote
diff --git a/apps/studio/lib/ai/tools/registry.ts b/apps/studio/lib/ai/tools/registry.ts
index a429a5e0588..384400e6a84 100644
--- a/apps/studio/lib/ai/tools/registry.ts
+++ b/apps/studio/lib/ai/tools/registry.ts
@@ -10,6 +10,7 @@ import { contract as getActiveIncidents } from './get-active-incidents'
import { contract as getNotebook } from './get-notebook'
import { contract as getReport } from './get-report'
import { contract as listDatabases } from './list-databases'
+import { contract as listExtensions } from './list-extensions'
import { contract as listNotebooks } from './list-notebooks'
import { contract as listPolicies } from './list-policies'
import { contract as listReports } from './list-reports'
@@ -17,7 +18,12 @@ import { contract as loadKnowledge } from './load-knowledge'
import { contract as renameChat } from './rename-chat'
import { contract as resolveSupportConversation } from './resolve-support-conversation'
import { contract as runNotebook } from './run-notebook'
-import type { ToolContract, ToolContractInput, ToolContractOutput } from './types'
+import type {
+ RemoteToolContract,
+ ToolContract,
+ ToolContractInput,
+ ToolContractOutput,
+} from './types'
import { contract as updateNotebook } from './update-notebook'
import { contract as updateOptInLevel } from './update-opt-in-level'
import type { AiOptInLevel } from '@/hooks/misc/useOrgOptedIntoAi'
@@ -72,6 +78,22 @@ export function getToolContract(toolName: string): ToolContract | undefined {
: undefined
}
+/**
+ * Remote MCP tools whose access Studio declares. Their parts stay `dynamic-tool`, so they aren't
+ * part of `StudioUIMessage`.
+ */
+export const REMOTE_TOOL_CONTRACTS = {
+ list_extensions: listExtensions,
+} as const satisfies Partial<Record<ToolName, RemoteToolContract>>
+
+export type RemoteContractToolName = keyof typeof REMOTE_TOOL_CONTRACTS
+
+/** The contract for a migrated remote tool, or `undefined` if the tool hasn't been migrated. */
+export function getRemoteToolContract(toolName: string): RemoteToolContract | undefined {
+ const contracts: Partial<Record<string, RemoteToolContract>> = REMOTE_TOOL_CONTRACTS
+ return Object.hasOwn(contracts, toolName) ? contracts[toolName] : undefined
+}
+
/**
* Applies the contract's `toModelOutput` to a persisted tool part, for history replay (where
* the SDK doesn't call it). Returns `undefined` when the tool has no contract. An output that
diff --git a/apps/studio/lib/ai/tools/types.ts b/apps/studio/lib/ai/tools/types.ts
index 1afb6b2e9e9..9ba9258ba52 100644
--- a/apps/studio/lib/ai/tools/types.ts
+++ b/apps/studio/lib/ai/tools/types.ts
@@ -42,6 +42,12 @@ export type ToolContract<TInput = unknown, TOutput = unknown> = {
outputOnInvalid?: JSONValue
}
+/**
+ * A tool the remote MCP server implements. The server owns the description, input schema,
+ * execution and output; Studio decides only who may run it and whether it needs approval.
+ */
+export type RemoteToolContract = Pick<ToolContract, 'name' | 'minOptInLevel' | 'needsApproval'>
+
export type ToolContractInput<C extends ToolContract> = z.infer<C['inputSchema']>
export type ToolContractOutput<C extends ToolContract> = z.infer<C['outputSchema']>