Composio Supabase 集成指南：OAuth/API Key 连接、MCP 工具配置与权限排障

本指南以 Composio 开源仓库知识库文档 toolkits-supabase.md 为主体，系统讲解如何在 Composio 中连接 Supabase（OAuth2 与 API_KEY 两种认证方式）、配置其 MCP 工具与端点（托管版 https://api.supabase.com 与自托管自定义 base URL），以及排查权限与速率限制问题。读完本文，你将掌握从认证配置、连接发起、MCP 工具装载到故障定位的完整实战链路。

一、认识 Supabase Toolkit：认证方案与连接方式

Supabase 是开源的后端即服务（BaaS）平台，提供 Postgres 数据库、认证、存储与实时订阅 API。在 Composio 中，Supabase 作为一个标准 toolkit 被集成，供 AI Agent 调用其管理 API。

从仓库中 toolkit 元数据（ts/packages/cli/test/mocks/toolkits.json）可以看到 Supabase 的官方定义：

{
  "slug": "supabase",
  "auth_schemes": ["OAUTH2", "API_KEY"],
  "composio_managed_auth_schemes": ["OAUTH2"],
  "is_local_toolkit": false,
  "meta": {
    "description": "Supabase is an open-source backend-as-a-service providing a Postgres database, authentication, storage, and real-time subscription APIs for building modern applications",
    "categories": [{ "id": "developer-tools-&-devops", "name": "developer tools & devops" }]
  },
  "no_auth": false
}

这里蕴含了几个关键事实：

• 两种认证方案：auth_schemes 为 ["OAUTH2", "API_KEY"]，即 Supabase 同时支持 OAuth2 和 API Key 两种方式，与知识库文档「Supabase supports both OAuth2 and API_KEY auth」完全对应。
• 托管认证：composio_managed_auth_schemes 为 ["OAUTH2"]，说明 OAuth2 可以由 Composio 托管；而 API_KEY 需要用户自行提供令牌。
• 非本地工具：is_local_toolkit: false 且 no_auth: false，表示该 toolkit 必须连接 Supabase 账号后才能执行工具。

同时，在 ts/packages/cli/src/generated/toolkit-slugs.ts 中可以看到 supabase、supabase_mcp、supabase_read_mcp 等多个 slug，说明仓库中还存在 MCP 形态的 Supabase 集成（详见下文第三节）。

二、连接 Supabase：OAuth2 与 API Key 两种认证路径

知识库文档给出的核心连接原则是：无论使用 SDK 还是直接调用 API，能力边界一致——SDK 只是同一套 API 的封装（"SDKs are wrappers over the same APIs, so anything possible through the SDK should be possible through the API"）。因此下面两个路径可以互相印证。

2.1 确认授权组织（Organization Scope）

Supabase 的授权通常以组织（organization）为作用域。如果遇到项目（project）或账号访问问题，先确认已连接凭据属于哪个 Supabase 组织/账号，再判断是否是 toolkit 本身的问题——不要把组织级权限问题误判为工具配置问题。

2.2 OAuth2 路径：创建 Auth Config 并发起连接

OAuth2 流程中，先创建（或复用）一个 OAuth2 类型的 auth config。仓库示例 python/examples/auth_configs.py 展示了自定义 OAuth 应用的 auth config 创建方式：

from composio import Composio

composio = Composio()

# 使用 Composio 托管认证
auth_config = composio.auth_configs.create(
    toolkit="github",
    options={"type": "use_composio_managed_auth"},
)
print(auth_config)

# 使用自定义 OAuth 应用
auth_config = composio.auth_configs.create(
    toolkit="notion",
    options={
        "name": "Notion Auth",
        "type": "use_custom_auth",
        "auth_scheme": "OAUTH2",
        "credentials": {
            "client_id": "1234567890",
            "client_secret": "1234567890",
            "oauth_redirect_uri": "https://backend.composio.dev/api/v1/auth-apps/add",
        },
    },
)

对于 Supabase，将 toolkit 换成 "supabase" 即可。随后通过 connected_accounts.initiate 发起 OAuth 连接，获得授权链接后引导用户完成认证（python/examples/connected_accounts.py）：

from composio import Composio

composio = Composio()
user_id = os.environ["COMPOSIO_EXAMPLES_USER_ID"]

connection_request = composio.connected_accounts.initiate(
    user_id=user_id,
    auth_config_id=gmail_auth_config_id,  # 换成 Supabase 的 auth_config_id
    allow_multiple=True,
)

# 将用户导向该 URL 完成授权
print(f"Visit this URL to authorize: {connection_request.redirect_url}")

# 等待连接建立（OAuth）
connected_account = connection_request.wait_for_connection()
print(f"Connected account {connected_account.id} is {connected_account.status}")

2.3 API_KEY 路径：传入 supabase_personal_token

API Key 认证的关键约束在文档中明确强调：必须把 Supabase 个人令牌（personal token）作为 supabase_personal_token 字段传入。也就是说，在创建 connected account 时，不能使用 generic_api_key 之类的通用字段名，而要使用 Supabase toolkit 规定的专用字段名。

文档同时给出一个自查手段：调用 /api/v3/toolkits/supabase 端点即可查看创建 connected account 时必需的初始化字段名（required connected-account initiation field）。这与 SDK 侧的 get_connected_account_initiation_fields 能力一一对应（python/examples/connected_accounts.py）：

required_fields = composio.toolkits.get_connected_account_initiation_fields(
    toolkit="NOTION",   # 换成 "SUPABASE"
    auth_scheme="API_KEY",
)
print(required_fields)

结合示例中 API Key 连接的实际写法（python/examples/connected_accounts.py），Supabase 场景下应大致形如：

connection_request = composio.connected_accounts.initiate(
    user_id=user_id,
    auth_config_id=supabase_apikey_auth_config_id,
    config=auth_scheme.api_key(
        options={"supabase_personal_token": "<你的 Supabase 个人令牌>"},
    ),
)
print(connection_request)

注意：supabase_personal_token 字段名以 /api/v3/toolkits/supabase 返回的字段定义为准，API 是字段名的权威来源。

2.4 在 Cursor 中显式发起连接

当在 Cursor 等 MCP 客户端中使用 Supabase 时，知识库文档特别指出：需要显式要求 Cursor/MCP 客户端先发起 Supabase 连接。MCP 服务器会提供一个 OAuth 链接，用户完成认证后，Supabase 工具才能基于该 connected account 执行。换言之，在 Cursor 里直接调用 Supabase 工具前，务必先走一遍「发起连接 → 用户授权」的步骤，否则工具会因缺少可用连接而失败。

三、配置 Supabase 工具与端点

3.1 在 MCP 服务器中显式配置 SQL 工具

SUPABASE_BETA_RUN_SQL_QUERY（在 Supabase 上执行 SQL 查询的 beta 工具）仍然受支持。但在简化的 Supabase MCP 页面中它可能不会默认展示，此时需要：

1. 创建 Supabase 集成 / MCP 服务器；
2. 在该 MCP 服务器中显式配置 Supabase SQL 工具，即使它没有出现在简化页面上。

仓库中 supabase_mcp、supabase_read_mcp 等 slug（ts/packages/cli/src/generated/toolkit-slugs.ts）也佐证了 MCP 形态集成是官方支持的装载方式。

3.2 托管版：使用 https://api.supabase.com 作为 base URL

这是文档中最容易被忽视的配置点：

• 托管 Supabase（hosted）：base URL 必须是 https://api.supabase.com（Supabase 管理 API），不要使用项目自己的 Supabase URL（形如 https://<project-ref>.supabase.co），除非客户是自托管。
• 如果之前配错了 base URL，需要删除并重建 MCP 配置或连接，换成正确 base URL 后重试。

3.3 自托管版：通过自定义 base URL 指向自建实例

• Supabase 工具默认指向托管版 https://api.supabase.com；
• 当前版本的 toolkit 可以接受自定义 base URL，用于连接自托管（self-hosted）的 Supabase 实例；
• 如果自托管连接失败，请依次检查：toolkit 版本是否支持自定义 base URL、自定义 base URL 是否传入了正确的受支持字段。

3.4 OAuth Scope：在 Supabase OAuth 应用上配置，而非授权 URL

一个容易踩坑的设计差异：Supabase 将 Management API 的 OAuth scopes 配置在 OAuth 应用上，而不是写在授权 URL（authorization URL）中。正确做法是：

1. 在客户自己的 Supabase OAuth 应用中设置所需 scopes（Composio 默认 OAuth 应用可能配置了更宽的权限——这一点在 docs/content/toolkits/faq/supabase.md 中亦有佐证：建议在用户自己的 OAuth 应用中限制 scope，而不是依赖 Composio 默认应用）；
2. 在 Composio 中创建对应的 auth config（指向该自定义 OAuth 应用）；
3. 重新连接（reconnect），让新的授权 grant 生效。

即：权限收窄要在客户自己的 OAuth 应用里做，Composio 只负责按该应用创建 auth config 并发起连接。

四、排查权限与速率限制问题

4.1 权限错误：先验证 Provider 侧访问控制

如果 Supabase 返回权限/访问控制错误，请先验证已连接的 Supabase 账号在 Supabase 侧是否拥有所需权限。这类错误很可能是 Provider 端（Supabase 服务器）的访问控制失败，而不是 Composio 的问题。排查顺序建议：

1. 在 Supabase Dashboard 确认账号/组织角色与项目成员关系；
2. 确认 OAuth scopes 是否覆盖了所调用工具需要的 Management API 权限；
3. 确认 API Key 对应的个人令牌是否具备目标项目权限；
4. 若均正常，再回到 Composio 侧检查连接状态与配置。

4.2 速率限制：捕获底层错误而非 Agent 包装消息

看到 rate-limit 提示时，请抓取底层的 Composio / tool / provider 错误，而不是 Agent 包装后的消息。原因在于：限流可能来自外部 provider（如 Supabase 自身）或 agent 层，而非 Composio 服务本身——Composio 不强制施加硬性服务限流（这一点同样记录在 docs/content/kb/guide/toolkits-supabase.mdx 的关键词与 FAQ 中）。判断步骤：

1. 查看原始错误中的状态码与错误体，判断限流来源（429 通常来自 provider）；
2. 区分「Composio 平台限流」与「Supabase API 限流」；
3. 若来自 Supabase，按 Supabase 的速率限制调整调用频率或增加配额。

五、快速自查清单

场景	检查项
连接失败	凭据属于哪个 Supabase 组织？是否 org 级授权问题
API Key 认证	字段名是否为 supabase_personal_token（以 /api/v3/toolkits/supabase 返回为准）
MCP 中无 SQL 工具	是否在 MCP 服务器中显式配置了 SUPABASE_BETA_RUN_SQL_QUERY
托管版连接失败	base URL 是否为 https://api.supabase.com（而非项目 URL）
自托管连接失败	toolkit 版本是否支持自定义 base URL、字段是否传对
权限不足	Supabase 账号角色、OAuth scopes（在 OAuth 应用上配）、API Key 权限
速率限制	抓取底层错误判断限流来自 provider 还是 agent 层

六、延伸阅读

• 知识库原文：docs/kb/articles/toolkits-supabase.md
• 知识库排版版（含来源与别名信息）：docs/content/kb/guide/toolkits-supabase.mdx
• FAQ 补充（scope 应在用户自己的 OAuth 应用上限制）：docs/content/toolkits/faq/supabase.md
• Auth Config 完整示例：python/examples/auth_configs.py
• Connected Account 发起连接示例：python/examples/connected_accounts.py
• Toolkit 元数据（认证方案定义）：ts/packages/cli/test/mocks/toolkits.json
• Toolkit slug 列表：ts/packages/cli/src/generated/toolkit-slugs.ts