Supabase Claude Code MCP
Workflow GuideSupabase Claude Code MCP
安全工作流指南
Turn database context into a controlled inspect, draft, review, and verify loop without handing an agent unrestricted production access.
把数据库上下文转化为可控的检查、起草、审核与验证闭环，
同时避免向智能体开放不受限制的生产环境权限。
TL;DR核心摘要
Start project-scoped and read-only. Capture the relevant schema, policies, indexes, migrations, advisors, and application assumptions before designing a change.
Require a migration plan, exact SQL, dependencies, lock and backfill risks, rollback, and tests. A plausible explanation is not an executable approval.
Apply an approved change to an isolated development project or branch, never directly to production data through an agent session.
Check resulting schema and policies, run security and performance advisors, test data behavior, and confirm application paths before promotion.
从限定项目的只读连接开始，先收集相关结构、策略、索引、迁移、顾问结果与应用假设，再设计变更。
要求提交迁移计划、准确 SQL、依赖、锁与回填风险、回滚和测试。解释看似合理，并不代表已经获准执行。
获批变更只能应用到隔离的开发项目或分支，不能让智能体会话直接修改生产数据。
检查实际结构与策略，运行安全和性能顾问，验证数据行为，再确认应用路径后才能准备升级。
Supabase Claude Code MCP works best as a guarded database development loop, not an autonomous production operator. The loop is evidence-driven: inspect the current state, draft the smallest reviewable change, obtain human approval, apply it only in development, verify the database and application behavior, and promote through the team's normal migration pipeline. Keep every phase independently observable so a wrong assumption is caught before it becomes a write.
Supabase Claude Code MCP 最适合充当受控的数据库开发闭环，而不是自主操作生产环境的工具。整个闭环要以证据为基础：检查当前状态、起草最小且可审核的变更、获得人工批准、只在开发环境执行、验证数据库与应用行为，最后通过团队原有迁移管线升级。每个阶段都要能单独核验，才能在错误假设变成写入前及时发现。
Understand the Supabase Claude Code MCP architecture理解 Supabase Claude Code MCP 的工作架构
Claude Code is the reasoning client, the official hosted Supabase MCP server exposes selected tool groups, and the bound development project remains the system of record. OAuth grants access under the authenticated developer account. The URL then narrows that authority with project_ref, read_only=true, and features. These controls complement one another: account permissions define the ceiling, project scope limits the target, read-only limits database mutation, and feature groups reduce visible actions.
Claude Code 负责推理，Supabase 官方托管 MCP 服务提供所选工具组，绑定的开发项目仍是权威数据源。OAuth 按已登录开发者账户授予访问，地址再通过 project_ref、read_only=true 与 features 缩小权限。几项控制相互补充：账户权限决定上限，项目绑定限制目标，只读模式限制数据库修改，功能组减少可见操作。
| Layer层级 | Responsibility职责 | Evidence to retain应保留的证据 | Primary risk主要风险 |
|---|---|---|---|
| Claude CodeClaude Code | Turns intent and repository context into proposed tool calls.把需求与仓库上下文转成工具调用提案。 | Prompt, selected tool, arguments, and approval.提示词、工具、参数与批准记录。 | Incorrect assumptions or prompt injection.错误假设或提示注入。 |
| Supabase MCPSupabase MCP | Translates approved calls into documented Supabase operations.把获批调用转换为文档规定的 Supabase 操作。 | Server URL, scope, feature groups, tool result, and error.服务地址、范围、功能组、工具结果与错误。 | Too many tools or the wrong project.工具过多或项目选错。 |
| Development project开发项目 | Holds the schema, data, policies, functions, migrations, and logs under test.承载待测结构、数据、策略、函数、迁移与日志。 | Before/after schema, advisors, tests, logs, and migration history.变更前后结构、顾问、测试、日志与迁移记录。 | Sensitive data, destructive SQL, or unreviewed drift.敏感数据、破坏性 SQL 或未审查漂移。 |
| Repository workflow仓库流程 | Stores reviewed migration files, application changes, tests, and deployment history.保存已审查迁移、应用修改、测试与发布历史。 | Diff, review, CI result, approver, and release record.差异、评审、CI 结果、批准人与发布记录。 | Bypassing version control with direct changes.直接修改绕过版本控制。 |
Use the current Supabase MCP guide to configure the hosted endpoint and tools. Supabase changes frequently; record the reviewed URL and date with the project rather than assuming an older feature list still matches the service.
托管端点和工具配置应以当前 Supabase MCP 指南为准。Supabase 更新较快，应在项目中记录已审查地址和日期，不要假设旧功能列表仍与现有服务一致。
Build an inspect, draft, review, and verify loop建立检查、起草、审核与验证闭环
Have Claude identify the server, project, branch, schemas, and read-only state. Inspect only objects related to the feature: table definitions, relationships, indexes, policies, views, functions, migrations, and relevant advisors. Ask it to distinguish observations from assumptions.
Describe the desired application behavior and acceptance criteria. Claude should propose one reviewable migration with exact SQL, affected objects, dependency order, expected locks, data backfill strategy, compatibility concerns, rollback, and tests. It must stop before execution.
Check destructive statements, constraint validation, index build cost, long transactions, policy coverage, view security, function privileges, default grants, and data transformations. Confirm that an UPDATE policy has the required SELECT path and that ownership conditions protect individual rows.
Use a migration file in version control and the team's established migration path. If direct SQL is used for exploration, keep it in a disposable environment and convert the approved final state into a clean migration rather than leaving undocumented drift.
Re-read the affected schema, migration history, policies, and advisors. Test expected access as each relevant role, rejected access for non-owners, application queries, generated types, rollback assumptions, and performance-sensitive paths. Compare evidence with the original acceptance criteria.
Commit the reviewed migration and tests, obtain code review, run CI, and deploy with the team's release controls. Record the production verification plan, but do not repoint the interactive MCP session at production to perform the promotion.
让 Claude 说明服务、项目、分支、schema 和只读状态，只检查当前功能相关对象：表定义、关系、索引、策略、视图、函数、迁移与顾问结果，并明确区分观察事实和推测。
说明目标应用行为与验收条件。Claude 应给出一份可审核迁移，包含准确 SQL、受影响对象、依赖顺序、预期锁、数据回填、兼容性、回滚和测试，然后在执行前停止。
检查破坏性语句、约束验证、索引构建成本、长事务、策略覆盖、视图安全、函数权限、默认授权和数据转换。还要确认 UPDATE 策略具备所需 SELECT 路径，并通过所有权条件限制每一行。
正式变更应通过版本控制中的迁移文件和团队既有流程执行。探索阶段即使直接运行 SQL，也只能在可丢弃环境中操作；最终获批的变更必须整理成清晰的迁移文件，避免出现无记录的结构漂移。
重新读取受影响结构、迁移历史、策略与顾问，分别测试相关角色的预期访问、非所有者的拒绝访问、应用查询、生成类型、回滚假设和性能敏感路径，并与最初验收条件逐项对照。
提交已审查迁移和测试，完成代码评审、CI 与团队发布控制。可以记录生产验证计划，但不要为了发布而把交互式 MCP 会话改接到生产环境。
Approval boundary: approving a plan is not the same as approving its execution. The review should name the exact migration, target development environment, allowed tools, verification steps, and stop condition. Any generated SQL that differs from the reviewed version requires a new approval.
批准边界：同意方案不等于同意执行。审查记录应写明具体迁移、目标开发环境、允许使用的工具、验证步骤和停止条件。实际生成 SQL 只要与审查版本不同，就必须重新批准。
Write prompts that preserve database intent用提示词准确保留数据库变更意图
Name the project, branch, schema, feature, and objects in scope. Tell Claude which tools it may use, explicitly forbid writes until approval, and identify files it may edit in the repository.
Ask for observed definitions, policies, migrations, advisors, and application call sites. Require citations to object names and separate facts, assumptions, and unanswered questions before a migration is drafted.
Require a change summary, SQL, affected objects, risk analysis, data migration strategy, rollback, test matrix, and explicit “stop before apply.” A stable format makes review faster and missing sections visible.
Specify expected reads and writes by role, denied cases, query plans or latency bounds where relevant, application tests, advisor findings, and the evidence needed before promotion.
明确项目、分支、schema、功能和涉及对象，说明 Claude 可以使用哪些工具，批准前禁止写入，并指定允许修改的仓库文件。
要求列出实际定义、策略、迁移、顾问和应用调用位置，并引用对象名称；起草迁移前，把事实、假设和待确认问题分开。
提案必须包含变更摘要、SQL、受影响对象、风险分析、数据迁移、回滚、测试矩阵，以及“执行前停止”。固定格式能加快审查，也让缺失内容更明显。
说明各角色预期读写、应被拒绝的情况、必要时的查询计划或延迟约束、应用测试、顾问结果，以及升级前必须取得的证据。
Reusable prompt: “Use only the project-scoped Supabase MCP server in read-only mode. Inspect the objects related to [feature] in [schema] and the repository migrations that define them. Report facts, assumptions, and questions. Then propose the smallest migration with exact SQL, risks, rollback, and tests. Do not execute SQL, apply a migration, deploy a function, or change data.”
可复用提示词：“只使用已限定项目且保持只读的 Supabase MCP 服务。检查 [schema] 中与 [feature] 相关的对象，以及仓库中定义它们的迁移文件。分别报告事实、假设与问题，再提出最小迁移，包含准确 SQL、风险、回滚与测试。不要执行 SQL、应用迁移、部署函数或修改数据。”
Apply production-grade safety boundaries为生产环境设置可靠的安全边界
Supabase describes this MCP server as a development and testing tool. Use a development project or branch with synthetic or obfuscated data. Read-only mode still permits disclosure of readable data, so it does not make a production connection safe.
Rows, logs, function source, and imported text can contain prompt injection. Keep manual tool approval enabled and reject any call whose purpose or target changes after external content is read.
Use browser OAuth for interactive access. Keep service-role and personal access tokens out of prompts, repository files, screenshots, logs, and shell history. Rotate any credential that may have been exposed, and recheck the shared project URL before approval.
Enable RLS on exposed tables and use policies that express ownership, not merely an authenticated role. Review view security, function execution grants, SECURITY DEFINER, schema exposure, and the difference between Data API grants and row policies.
Supabase 把该 MCP 服务定位为开发与测试工具。应使用只含模拟或脱敏数据的开发项目或分支。只读模式仍能泄露可读取内容，因此不能让生产连接自动变得安全。
数据行、日志、函数源码与导入文本都可能包含提示注入。保持人工工具审批；读取外部内容后，只要调用目的或目标发生变化，就应拒绝。
交互式访问使用浏览器 OAuth。服务角色与个人访问令牌不得进入提示词、仓库文件、截图、日志或命令历史。可能泄露时立即轮换，并在批准共享项目地址前重新核对。
暴露表要启用 RLS，策略必须表达数据所有权，不能只判断 authenticated 角色。同时检查视图安全、函数执行授权、SECURITY DEFINER、schema 暴露，以及 Data API 授权与行策略之间的区别。
Extend the workflow beyond Supabase with QVeris通过 QVeris 将工作流扩展到 Supabase 之外
Supabase MCP should remain the focused path for database context and backend operations. The QVeris Tool and Provider directories currently return no exact Supabase record, so this page uses QVeris Docs and the Playground for complementary discovery instead of claiming a direct integration.
Supabase MCP 仍应专门负责数据库上下文与后端操作。当前 QVeris Tool 与 Provider 目录都没有返回完全对应的 Supabase 条目。如果任务还需要其他外部能力，可以查阅 QVeris 文档，并在 Playground 中继续寻找；本页不会把它描述成 Supabase 的直接集成。
- Keep project schema, policies, migrations, logs, and development changes inside Supabase MCP.
- Use QVeris only when discovery returns a separate external capability; inspect its provider and schema before use.
- Validate external data before it enters a migration or table, and require approval before any cross-system write.
- 项目结构、策略、迁移、日志与开发变更继续由 Supabase MCP 管理。
- 只有检索返回独立外部能力时才使用 QVeris，并在使用前检查供应商与参数结构。
- 外部数据进入迁移或数据表前先校验；任何跨系统写入都需要人工批准。
FAQ常见问题
It may be technically possible, but production changes should remain reviewable and explicitly approved. Generate a migration, inspect the diff, use the normal deployment path, and verify afterward.
Confirm the authenticated account, project reference, branch, schema, and permissions. Empty output often means the wrong scope rather than missing data.
Use read-only SQL for inspection in development. Durable approved schema changes belong in reviewed migration files so repository history and deployment environments stay aligned.
Do not assume so. MCP runs with authenticated developer permissions, and some privileged database paths can bypass application-level expectations. Review the exact role and operation.
Compare schema and policies, inspect migration history, run security and performance advisors, test allowed and denied access, and exercise affected application queries.
Supabase recommends its MCP server for development and testing. Promote reviewed repository changes normally; do not make an interactive agent a production operator.
技术上可能实现，但生产环境变更应保持可审核并经过明确批准。先生成迁移、检查差异，再通过既有发布流程应用，最后完成验证。
请确认已登录账户、项目引用、分支、数据库模式与权限。空结果往往表示访问范围错误，并不一定说明数据不存在。
开发环境检查可以使用只读 SQL；需要长期保留的获批结构变更应进入迁移文件，确保仓库历史与各发布环境一致。
不能直接假设。MCP 按已授权开发者权限运行，部分高权限数据库路径可能绕过应用层预期，必须检查具体角色与操作。
比对结构与策略，检查迁移历史，运行安全和性能顾问，测试允许与拒绝访问，并执行受影响的应用查询。
Supabase 建议 MCP 服务用于开发和测试。应正常升级已审查的仓库变更，不要让交互式智能体成为生产操作者。
References and next steps参考资料与下一步
Supabase MCP guide
Supabase MCP repository
Claude Code MCP documentation