使用 goose 接入 Supabase MCP 服务器：远程 Streamable HTTP 扩展配置与实战指南

Supabase 官方托管了云端的 Supabase MCP 服务器，你可以把整个 Supabase 后端能力——项目管理、数据库表查询、Edge Functions 部署与运维等——直接交给 goose 这个可扩展 AI Agent 调用。本文是《goose 扩展指南》系列中针对 Supabase MCP 的完整实战教程，将带你完成从扩展安装、OAuth 授权到真实业务操作（列出项目、查看表结构、部署 Edge Function）的全流程，并深入源码说明 goose 内部如何解析这类远程扩展配置。

一、为什么选择 Supabase 官方托管的远程 MCP

在 goose 中，扩展（Extension）的本质是 MCP 服务器。goose 通过三种运输方式与 MCP 服务器通信，见 crates/goose/src/agents/extension.rs 中的 ExtensionConfig 定义：

• Command-line Extension（stdio）：type: stdio，本地启动一个子进程，通过标准输入输出通信；
• Built-in Extension：goose 自带的本地 MCP 服务器能力；
• Remote Extension（Streamable HTTP）：type: streamable_http，通过网络 HTTP 连接远程 MCP 端点。

Supabase 官方在 https://mcp.supabase.com/mcp 托管了 Supabase MCP Server，属于典型的第三种。它把官方 Supabase CLI 与 Management API 的能力包装成 MCP 工具，并采用 OAuth 2.0 授权进行身份认证。这意味着：你不需要本地安装任何 Supabase 工具链、不需要维护 API Key，只要 goose 能联网，就能直接管理你的 Supabase 项目。

接入后 goose 可以帮你完成的操作包括：

• 列出并查看你名下所有 Supabase 项目及其运行状态、地域、数据库版本等配置信息；
• 发现项目内的数据库表结构（含 RLS 状态、行数、主外键），并执行数据查询；
• 直接创建、部署和管理 Supabase Edge Functions；
• 与 Supabase 后端进行更多 Management API 级别的交互。

从源码结构看，goose 把 stdio 与 streamable_http 并列视为完整的扩展类型：旧式的 sse 类型已被弃用，配置解析时若发现 type: sse 会给出 "SSE is unsupported, migrate to streamable_http" 的警告（见 crates/goose/src/config/extensions.rs 中 get_warnings() 的实现），因此新接入的远程服务器都应使用 Streamable HTTP 端点。

二、快速安装

无论使用 goose Desktop 还是 goose CLI，接入 Supabase 扩展只需提供一个端点地址：

https://mcp.supabase.com/mcp

方式一：goose Desktop（推荐新手）

如果你使用 goose Desktop，可以直接点击官方提供的一键安装链接（extension deep link）：

goose://extension?type=streamable_http&url=https%3A%2F%2Fmcp.supabase.com%2Fmcp&id=supabase&name=Supabase&description=Connect%20your%20Supabase%20projects%20to%20AI%20assistants.%20Manage%20tables%2C%20query%20data%2C%20deploy%20Edge%20Functions%2C%20and%20interact%20with%20your%20Supabase%20backend%20directly%20from%20your%20MCP%20client.

点击后 goose Desktop 会自动拉起扩展配置界面，扩展 ID 为 supabase、显示名称为 Supabase，随后浏览器会引导你完成 OAuth 登录授权（详见下文"OAuth 授权流程"）。

方式二：goose CLI

在终端运行 goose configure，选择新增 Remote Extension（Streamable HTTP） 类型，然后在询问端点时填入上面的 URL 即可，不需要配置任何环境变量：

goose configure

配置向导的交互提示大致如下（与 goose 文档站扩展组件中的真实向导文案一致，见 documentation/src/components/CLIExtensionInstructions.tsx）：

◆  What type of extension would you like to add?
│  ○ Built-in Extension
│  ○ Command-line Extension
│  ● Remote Extension (Streamable HTTP) (Connect to a remote extension via MCP Streamable HTTP)

◆  What is the Streamable HTTP endpoint URI?
│  https://mcp.supabase.com/mcp

◆  Please set the timeout for this tool (in secs):
│  300

◆  Would you like to add custom headers?  （选择 No）

关于向导中各项参数的默认值：扩展的超时（timeout）默认为 300 秒，这一默认值对应源码中 DEFAULT_EXTENSION_TIMEOUT: u64 = 300 常量（见 crates/goose/src/config/extensions.rs）。因为 Supabase MCP 采用 OAuth 授权，不需要在配置时手动填写 Authorization 头，所以自定义 headers 选择 No 即可。

三、深入配置：远程扩展的存储结构与字段含义

向导只是把配置写入了 goose 的配置文件（extensions 键下）。理解这一点，你就能手工校验甚至复刻这份配置。goose 配置解析的核心逻辑在 crates/goose/src/config/extensions.rs：

• 配置以 extensions: 为顶层键，每个子键对应一个扩展条目；
• 每个条目包含 enabled: true/false 与一个被 serde(flatten) 展开的 ExtensionConfig；
• 若某条配置解析失败，goose 会记录 "Skipping malformed extension config entry" 日志并跳过它，而不会破坏其他扩展条目（对应多个 test_*_preserves_unparseable_sibling 之类的测试用例）；
• 扩展的 key 由名称通过 name_to_key() 归一化得到（保留字母数字、_、-，去除空白，其余字符替换为 _，最后转小写），这就是为什么名称 Supabase 会对应 key supabase。

Supabase 扩展写入配置后的 YAML 结构大致如下：

extensions:
  supabase:
    enabled: true
    type: streamable_http
    name: Supabase
    description: Connect your Supabase projects to AI assistants. Manage tables, query data, deploy Edge Functions, and interact with your Supabase backend directly from your MCP client.
    uri: https://mcp.supabase.com/mcp
    timeout: 300

在 crates/goose/src/agents/extension.rs 中，ExtensionConfig::StreamableHttp 变体（#[serde(rename = "streamable_http")]）定义了该类型支持的全部字段：

字段	含义	说明
name	扩展名称	用于标识该扩展，也参与生成配置 key
description	扩展描述	帮助 LLM 理解该扩展用途，会进入系统提示
uri	MCP 端点地址	即 https://mcp.supabase.com/mcp
headers	自定义 HTTP 头	可含 $VAR/${VAR} 环境变量替换；OAuth 场景通常为空
envs / env_keys	环境变量/密钥引用	通过环境变量或 goose 密钥库注入敏感值
timeout	单次调用超时（秒）	新配置建议显式设置，默认 300
socket	Unix 域套接字路径	HTTP-over-UDS 传输专用，常规远程配置不需要
client_id	预注册的 OAuth Client ID	供不支持 Client ID Metadata/Dynamic Registration 的授权服务器使用，支持 $VAR 替换
client_secret_key	OAuth client secret 的密钥键名	值从 envs/env_keys 或配置密钥库解析，不落盘明文
scopes	请求的 OAuth 授权范围	为空时依据服务器元数据选择范围

Supabase 托管服务器支持标准的 OAuth 动态客户端发现，因此上述 OAuth 相关字段（client_id 等）都无需填写——goose 会在连接时自动完成授权协商。这也与 crates/goose/src/agents/extension.rs 中的测试用例所验证的一致：不带 client_id/client_secret_key/scopes 的 streamable_http 配置可以正常反序列化，且序列化时会自动省略这些未设置的字段。

四、OAuth 授权流程

Supabase Remote MCP 的鉴权完全基于 OAuth：

1. 首次通过 goose 连接 Supabase MCP 服务器时，goose 会启动本地的 OAuth 回调并打开浏览器窗口；
2. 浏览器跳转到 supabase.com，提示你登录自己的 Supabase 账号；
3. 按页面提示授权 goose 访问你的 Supabase 项目（授权范围通常覆盖项目管理、数据库查询与 Edge Functions 操作）；
4. 授权成功后，token 由 goose 安全保存，之后每次调用 Supabase 工具都会自动携带凭据，无需再手动输入 API Key。

安全提示（务必阅读）：Supabase MCP 服务器赋予的是真实的数据库与项目管理能力，其工具可以执行诸如建表、改数据、部署函数等有实际影响的操作。请务必在执行前仔细复核 LLM 请求的动作，并确认你当前连接的是正确的环境（development / staging / production），避免在错误环境上执行破坏性操作。有关 goose 侧的权限与审批机制，可进一步查阅 documentation/docs/guides 下关于权限与配置的说明。

五、实战示例

接入并授权成功后，即可在 goose 会话中直接用自然语言操作 Supabase。以下是三个最典型的场景。

示例 1：列出你的 Supabase 项目

goose Prompt：

List all my Supabase projects

goose 输出示例：

Here are your Supabase projects:

1. my project (ID: abc123xyz789defg)
   - Region: US West 1
   - Created: October 30, 2025
   - Status: ACTIVE_HEALTHY
   - Database: PostgreSQL 17.6.1.031 (Engine v17)
   - Host: db.abc123xyz789defg.supabase.co

2. new project (ID: jkl456mno012pqrs)
   - Region: US West 1
   - Created: October 31, 2025
   - Status: INACTIVE
   - Database: PostgreSQL 17.6.1.032 (Engine v17)
   - Host: db.jkl456mno012pqrs.supabase.co

Would you like more detailed information about any specific project?

可以看到，goose 汇总了每个项目的地域、创建时间、健康状态、数据库版本与数据库主机地址，这些信息来自 Supabase Management API 的只读端点，适合用于巡检多个项目的运行状况。

示例 2：查询项目中的数据库表

goose Prompt：

What tables exist in my project?

goose 输出示例：

Tables in my project (public schema):

1. users
   - RLS Enabled: Yes
   - Row count: 150
   - Columns: id (uuid), email (text), name (text), created_at (timestamptz), role (text)
   - Primary Key: id
   - Foreign Keys: Referenced by posts.user_id, profiles.user_id

2. posts
   - RLS Enabled: Yes
   - Row count: 342
   - Columns: id (uuid), user_id (uuid), title (text), content (text), created_at (timestamptz)
   - Primary Key: id
   - Foreign Keys: References users.id, referenced by comments.post_id

3. comments
   - RLS Enabled: Yes
   - Row count: 1089
   - Columns: id (uuid), post_id (uuid), user_id (uuid), content (text), created_at (timestamptz)
   - Primary Key: id
   - Foreign Keys: References posts.id, references users.id

4. profiles
   - RLS Enabled: Yes
   - Row count: 150
   - Columns: id (uuid), user_id (uuid), bio (text), avatar_url (text), updated_at (timestamptz)
   - Primary Key: id
   - Foreign Keys: References users.id

5. categories
   - RLS Enabled: No
   - Row count: 12
   - Columns: id (uuid), name (text), description (text), created_at (timestamptz)
   - Primary Key: id

Would you like to query data from any of these tables?

goose 一次性返回了 public schema 下所有表的元数据：是否开启 RLS、行数、全部列及类型、主键、外键关系。得到这张"表地图"后，你可以继续追问，例如让 goose 直接对某张表执行 SQL 查询、生成统计或定位数据问题。

示例 3：部署一个 Edge Function

goose Prompt：

Deploy a new Edge Function called 'hello-world' that returns a simple JSON response

goose 输出示例：

Edge Function deployed successfully!

Function Name: hello-world
Version: 1
Status: ACTIVE
Function ID: c4e03748-3e72-45e2-bdca-03f7e4800874
Project: my project (tabowbdrhvtlvzvfyinw)
Entrypoint: index.ts
JWT Verification: Enabled
Created: November 8, 2025

Function code:
~~~typescript
Deno.serve(async (req) => {
  return new Response(
    JSON.stringify({ message: "Hello World!" }),
    { headers: { "Content-Type": "application/json" } },
  )
})
~~~

Endpoint:
https://tabowbdrhvtlvzvfyinw.supabase.co/functions/v1/hello-world

这个例子展示的是有写入副作用的工具调用：goose 生成了基于 Deno 的 Edge Function 代码、在云端完成了部署并返回函数 ID、JWT 校验状态与可访问的 HTTPS 端点。这也是前文"安全提示"需要重点关注的场景——让 goose 帮你写好代码并部署非常高效，但涉及生产环境前务必确认改动范围。

六、延伸阅读

• 想了解扩展配置写入的具体文件格式与存储位置，可阅读 documentation/docs/guides/config-files.md；
• goose 其余官方/社区 MCP 扩展教程（GitHub、Neon、Vercel、Cloudflare 等）均位于 documentation/docs/mcp 目录，本页位于其中的 documentation/docs/mcp/supabase-mcp.md；
• 远程扩展的类型定义、字段说明与解析测试集中在 crates/goose/src/agents/extension.rs 与 crates/goose/src/config/extensions.rs，需要排查扩展加载问题时可直接查看这两处。