Stripe 的 MCP 服务器让 Claude Code 在你开发时查阅 Stripe 的文档、读取你的账户,并创建产品、价格和支付链接等对象。Stripe 的文档称,2026 年 11 月 30 日之后,其 MCP 服务器将不再接受完全访问权限的密钥(secret key)以及没有 Agent 标签的受限密钥(restricted key)。如果你几个月前通过把密钥粘贴到配置文件中来设置 Stripe MCP,这个连接将在 12 月停止工作。本指南面向用 Claude Code 独自开发的创始人:如何按 Stripe 现在推荐的方式连接 Stripe,为什么要从沙盒开始,如何在智能体配置文件中找到旧密钥,如何迁移,以及当你是账户中唯一的人时审批如何运作。即使没有 Soloop 账户,本指南也同样有用;它不构成安全审计。
简短回答
安装 Stripe CLI 并运行 stripe agent setup。它会检测到 Claude Code 并安装 Stripe 的插件,该插件会配置位于 mcp.stripe.com 的托管 MCP 服务器以及 Stripe 的技能(skills)。启动 Claude Code,运行 /mcp,并通过 OAuth 登录 Stripe。在 Stripe 的授权同意页面上,先授予一个沙盒,只在需要时再添加正式模式(live mode)。
如果你的任何工具向 mcp.stripe.com 发送 sk_ 密钥或没有 Agent 标签的 rk_ 受限密钥,请在 2026 年 11 月 30 日之前替换它:用 OAuth 重新连接,或者创建一个只具备该任务所需权限的智能体 API 密钥,并从环境变量中加载它。让退款和订阅取消保持在审批之后,并且永远不要让 Claude Code 始终允许 Stripe 的写入工具。
2026 年 11 月 30 日有什么变化
Stripe 的 MCP 服务器支持两种登录方式:OAuth,适用于代表你的 Stripe 用户账户操作的客户端;以及智能体 API 密钥(agent API key),适用于需要独立、持久访问的 AI 应用。智能体 API 密钥是一种在创建时被标记为属于自主智能体的受限密钥。它的身份验证方式与其他受限密钥相同,但会自动受 Stripe 审批规则的约束。
从 12 月开始,使用完全访问权限的密钥或没有 Agent 标签的受限密钥向 MCP 服务器发出的请求,会收到带有 OAuth 发现质询(discovery challenge)的 401 响应。Stripe 的通知针对的是发送到其 MCP 服务器的密钥。它没有说你的应用用来向客户收款的密钥会发生变化;你的应用在自己服务器上使用的密钥是另一个问题,适用 Stripe 优先使用受限密钥的一般建议。
「在 2026 年 11 月 30 日之前完成迁移。从 12 月开始,Stripe MCP 将不再接受完全访问权限的密钥以及没有 Agent 标签的受限 API 密钥。请用新创建的智能体 API 密钥替换这些密钥,或用 OAuth 重新连接。」
Stripe 文档:Model Context Protocol交互式 MCP 客户端使用 OAuth;它让你无需共享 API 密钥即可授权和撤销客户端。对于无法使用 OAuth 的自主客户端,创建一个只具备客户端所需权限的智能体 API 密钥,先在沙盒中测试,然后让旧密钥过期。
Stripe 文档:Model Context Protocol要把受限密钥标记为智能体密钥,在 Stripe 询问密钥的预期用途时选择「Authorizing agent access to your account」。带 Agent 标签的密钥受审批规则约束;你创建第一个此类密钥时,Stripe 会添加默认规则。
Stripe 文档:API keys@stripe/mcp 和 @stripe/agent-toolkit 软件包已被弃用,并且「将不再获得任何更新,包括安全修复」;Stripe 转而推荐托管服务器。
GitHub:stripe/ai哪种访问方式适合哪项任务
大多数在自己键盘前使用 Claude Code 的创始人只需要 OAuth。智能体密钥用于不需要你在场就会运行的工作,例如定时任务或在 CI 中运行的无界面智能体。
| 维度 | 适用场景 | 2026 年 11 月 30 日之后 |
|---|---|---|
| 通过插件或 /mcp 使用 OAuth | 你在 Claude Code、Codex 或 Cursor 中工作,并且可以通过浏览器登录。你在 Stripe 的授权同意页面上选择沙盒或正式账户以及权限。 | Stripe 推荐。可在 Stripe 用户设置的 OAuth sessions 下撤销会话。 |
| 放在环境变量中的智能体 API 密钥 | 智能体在你不在场时运行,或客户端无法使用 OAuth。该密钥只具备你设置的权限。 | 被接受。敏感操作遵循你的审批规则。 |
| 发送到 mcp.stripe.com 的密钥(sk_)或未加标签的受限密钥(rk_) | 把密钥粘贴到配置文件中的旧设置。 | 被拒绝并返回 401。请在截止日期之前替换。 |
| 带 --api-key 的本地 @stripe/mcp 软件包 | 旧教程用 npx 和密钥启动它。 | 已弃用,不再有安全修复。请迁移到托管服务器。 |
在 Claude Code 中设置 Stripe,先用沙盒
沙盒是一个隔离的 Stripe 测试环境:没有任何卡组织会处理其中的内容,其对象也永远不会与正式模式混在一起。在沙盒中开发意味着一条含糊的提示创建的是测试价格,而不是真实价格。
- 用 npm install -g @stripe/cli 或 Stripe 的安装脚本安装 Stripe CLI(版本 1.43.3 或更高)。
- 在你的项目目录中运行 stripe agent setup --client claude-code。随时运行 stripe agent setup --status 查看已安装的内容。
- 启动 Claude Code 并运行 /mcp。选择 Stripe 服务器并登录。在 Stripe 的授权同意页面上,授予一个沙盒和你需要的权限;暂时不要包含正式模式。
- 如果你是账户管理员,打开 Dashboard 中 MCP and CLI access 的设置,分别决定正式模式和沙盒是否允许 MCP。
- 保持 Claude Code 的工具审批开启,这样每次会更改内容的 Stripe 调用都会等待你确认。
- 先让它完成一项只读任务,例如「列出我的 Stripe 沙盒中的产品和价格」,并检查回答是否与 Dashboard 一致。
- 在接受真实付款之前,按照 Stripe 的上线检查清单(go-live checklist)操作。只为需要正式模式的任务向 MCP 连接授予正式模式。
在智能体配置中查找旧的 Stripe 密钥
请在终端中运行这些命令,而不要通过智能体运行,这样密钥值就不会进入 AI 对话记录。每条命令只输出文件名或提交 ID。这些命令已在 macOS 上用 grep 和 git 测试过;在 Linux 上,Claude Desktop 的配置位于其他位置。
- 保存了 Stripe 密钥的用户级智能体配置:grep -lE '(sk|rk)_(live|test)_' ~/.claude.json ~/.cursor/mcp.json ~/.codex/config.toml ~/Library/"Application Support"/Claude/claude_desktop_config.json 2>/dev/null
- 每个代码仓库中的项目配置,在其根目录下运行:grep -rlE '(sk|rk)_(live|test)_' .mcp.json .claude .cursor .vscode 2>/dev/null
- 哪些配置使用了 Stripe MCP:grep -rlE 'mcp\.stripe\.com|@stripe/mcp' ~/.claude.json .mcp.json .claude .cursor .vscode 2>/dev/null
- 密钥是否曾进入 git 历史:git log --all --oneline -G '(sk|rk)_(live|test)_' 会列出每一个添加或移除密钥的提交,包括你后来已删除的文件中的提交。
- 打开命令列出的每个文件,在 MCP 服务器条目、Authorization 请求头、--api-key 参数或已保存的命令权限中查找 Stripe 密钥。
在截止日期之前迁移
- 对于搜索找到的每个连接,先判断:你能用 OAuth 登录吗?如果能,就从配置中删除密钥,并运行 /mcp 重新连接。
- 如果任务必须在你不在场时运行,就在 API keys 页面上创建一个新密钥:选择 Create restricted key,选择「Authorizing agent access to your account」,并只授予该任务需要读取或写入的资源。先在沙盒中创建。
- 把密钥保存在你的机密管理工具或环境变量中,永远不要直接写在 .mcp.json 里,并按名称引用它(模板见下方)。
- 运行一次只读请求并确认成功。如果返回带 OAuth 质询的 401,说明该密钥没有被标记为智能体密钥。
- 让旧密钥过期;如果你的应用也在使用它,则带宽限期轮换。轮换期间,Stripe 允许新旧两个密钥同时生效最多 7 天。
- 删除所有用 npx 启动的 @stripe/mcp 条目,并改用托管服务器。
复制适用于智能体密钥的 .mcp.json
只在无法使用 OAuth 时使用它。把它保存为项目中的 .mcp.json,在启动 Claude Code 之前在 shell 或机密管理工具中设置 STRIPE_AGENT_KEY,并让 .env 文件和密钥本身远离 git。变量名只是示例;Stripe 的文档使用 AGENT_API_KEY。
只授予任务所需的权限
示意性示例,并非 Stripe 的默认设置:先确定任务,再确定权限。受限密钥和智能体密钥允许你把每种资源设为无(none)、读取(read)或写入(write)。
| 维度 | 授予 | 不授予 |
|---|---|---|
| 回答「这笔付款为什么失败?」 | 对客户、扣款(charges)、支付意图(payment intents)和账单(invoices)的读取权限。 | 所有写入权限。 |
| 开发时设置产品、价格和支付链接 | 在沙盒中对产品、价格和支付链接的写入权限。 | 上线之前的正式模式;退款和提现(payouts)。 |
| 每周收入汇总 | 对订阅、账单和余额的读取权限。 | 客户信息更新以及所有写入权限。 |
| 准备退款供你审阅 | 对退款的写入权限,并保留默认审批规则。 | 提现、转账和银行账户更改。 |
独自工作时的审批
这里有三道相互独立的关卡,它们各自承担不同的作用。Claude Code 自己的权限提示会在工具运行之前询问。Stripe 的人工确认(Human confirmation)适用于通过 OAuth 执行的某些操作,例如创建退款:Stripe 会给你的智能体一个链接,你在 24 小时内在 Dashboard 中批准,然后告诉智能体重试。Stripe 的审批规则适用于带 Agent 标签的密钥。
Stripe 为带 Agent 标签的密钥设定的默认规则,会把退款、订阅取消、提现、对外付款和转账以及货币兑换保留下来等待审核。智能体会收到 approval_required 错误,Stripe 会发起一个请求;你在 Dashboard 或 Stripe 移动应用中批准或拒绝它,请求在 14 天后过期。双人审批通常需要请求者以外的审核人,因此在只有一个人的 Stripe 账户中,你只能为带 Agent 标签的密钥执行的操作保存此类规则。这也是应该给无人值守的智能体一个专属智能体密钥、而不是使用你自己登录身份的另一个原因。
| 维度 | 它做什么 | 建议设置 |
|---|---|---|
| search_stripe_documentation, stripe_api_search, stripe_api_details | 搜索 Stripe 的文档和 API 参考。 | 允许。 |
| stripe_api_read, get_stripe_account_info | 读取已连接账户中的对象,包括客户数据。 | 在沙盒中允许;在正式模式中询问。 |
| stripe_api_write | 任何创建、更新或删除调用,从一个价格到一笔退款或一次订阅取消。 | 始终询问。永远不要选择「don't ask again」。 |
| send_money 等 Treasury 工具 | 从 Treasury 账户转出资金。 | 除非你在使用 Treasury,否则不要使用;Stripe 要求人工确认(Human confirmation)。 |
复制迁移工作表
你的电脑和每个代码仓库各用一份。记下每个连接及其新的访问方式,以便日后能干净地撤销。
Soloop 能做什么
Soloop 不会连接 Stripe、读取你的 Stripe 数据或管理 API 密钥。上述所有工作请使用 Stripe 的工具和 Dashboard。
Soloop 用于你能够收款之后的工作:根据 Soloop 手册,它可以附带资料来源调研市场,通过已连接的账户撰写和发布 X 帖子和回复,通过已连接的 Gmail 账户发送外联邮件,并在你完成设置和付款后准备 Google Ads 搜索广告系列,默认情况下各项操作都会等待你的审批。不要把 Stripe 密钥粘贴到任何 AI 工具的提示中,包括 Soloop。
资料来源、局限与更新
Stripe 的 Model Context Protocol、API keys、approvals、agent plugin、agent setup 和 skills 文档以及 stripe/ai 的 README 于 2026 年 11 月 11 日查阅。除了「从 12 月开始」,Stripe 没有公布更精确的截止时间。命令、权限组合和工具设置属于在一个示例目录上测试过的编辑建议,不是安全审计,也不是 Stripe 或 Anthropic 的声明。
本指南将在 2027 年 2 月 11 日之前复审;如果 Stripe 更改截止日期或其 MCP 服务器的身份验证方式,会更早复审。
带 Agent 标签的密钥的默认规则涵盖退款、订阅取消、对外付款和转账、提现以及货币兑换。请求在 14 天后过期。单用户账户只有在把执行者(actor)条件设为带 Agent 标签的 API 密钥时,才能保存双人审批规则。
Stripe 文档:Two-party approvalsstripe agent setup 会检测 Claude Code、Codex 和 Cursor,并安装相应的插件、技能和 MCP 服务器;--client 把它限定为一个工具,--status 显示已安装的内容。
Stripe CLI:agent setupSoloop 手册描述了附带资料来源的调研、通过已连接账户在 X 上发帖、Gmail 外联,以及在完成设置和付款后运行 Google Ads 搜索广告系列;默认先审批。它不连接 Stripe。
Soloop 产品手册