Stripe MCP Setup: Test Mode, Restricted Access, and Approval First
Use Stripe’s hosted remote MCP server at https://mcp.stripe.com with OAuth when your MCP client supports it. Otherwise, run the official Agent Toolkit server with a restricted test credential and a narrow explicit tool list, then prove read operations before enabling payment, refund, customer, or subscription writes.
Use Stripe’s hosted remote MCP server at https://mcp.stripe.com with OAuth when your MCP client supports it. Otherwise, run the official Agent Toolkit server with a restricted test credential and a narrow explicit tool list, then prove read operations before enabling payment, refund, customer, or subscription writes.
Table of contents
- Should you use hosted OAuth or the local package?
- How do you keep the first connection in test mode?
- How do you select restricted credentials and tools?
- How do you verify customers and products with reads?
- How do you gate payments, refunds, and subscription changes?
- How do you fix mode, account, permission, and missing-tool errors?
- FAQ
Should you use hosted OAuth or the local package?
Prefer Stripe’s hosted remote MCP server with OAuth when your MCP client supports it. If it does not, use the official Agent Toolkit server with a restricted test credential and an explicit, narrow tool selection. Stripe documents the hosted connection at its MCP documentation, while the local implementation is maintained in the Stripe Agent Toolkit.
The hosted option fits a client that can connect to a remote MCP server and complete OAuth. The local option fits a client that requires a locally configured API key and tool selection through @stripe/mcp. The package accepts an API key and explicit tools; --tools=all widens the available surface, so avoid that setting during the first connection.
This is a setup decision, not an approval decision. With either option:
- Confirm the intended Stripe account and mode.
- Start with test data and read operations.
- Keep credentials restricted to the smallest needed scope.
- Review every consequential write before it is sent.
Use MCPtrove’s Stripe MCP server directory page to keep the hosted endpoint and official package paths together while deciding which connection your client supports.
How do you keep the first connection in test mode?
Keep the first connection in Stripe sandbox or test mode and use a test credential; with hosted OAuth, authenticate the intended test account and mode before approving access. Before any write, review the account and mode in Stripe itself.
Stripe distinguishes sandbox/test data from live mode, so the connection should be treated as incomplete until that distinction is clear in the account context. The Stripe test-mode documentation explains the separation; use it as the reference point when confirming what the client is allowed to access.
| Connection path | First-run rule | Stop when |
|---|---|---|
| Hosted OAuth | Authenticate the intended test account and mode | The account or mode is unclear |
| Local package | Supply a restricted test API key | The key may be live or broadly scoped |
| Either path | Perform reads before writes | Returned data does not match expectations |
Do not rely on a model’s wording, a client label, or a confirmation dialog to identify live versus test data. If the account, mode, or returned records are unclear, stop and correct the connection before continuing. A test-mode first pass gives you a defined boundary for validating customers, products, and tool behavior.
How do you select restricted credentials and tools?
Use a restricted test API key and select only the tools required for the initial read pass. For the local package, provide the API key and an explicit tool selection; do not begin with --tools=all.
Stripe’s API key guidance distinguishes restricted keys from broader credentials. Apply that distinction to the first connection: choose the narrowest test credential that can support the records you need to inspect, then expose only the corresponding read tools.
A practical selection sequence is:
- Identify the read operations needed to verify the intended customer and product records.
- Create or select a restricted test credential for that scope.
- Configure the local package with that credential and an explicit tool list.
- Confirm that unneeded tools are not exposed.
- Expand access only after the read results and account context are correct.
Do not treat tool selection as a cosmetic client setting. It determines which operations the MCP server can present to the client. Before connecting, use the MCPtrove config validator as a practical checklist for the credential, mode, and selected tools.
How do you verify customers and products with reads?
Verify customers and products with read-only operations in test mode, using records whose account and mode you have already confirmed. Do not create, charge, refund, or modify anything until the returned records match the intended Stripe context.
Start with a known test customer or product record. Ask the client to retrieve it, then check that the result belongs to the account and mode you expected. Repeat the same process for the product information needed by your workflow. The goal is to establish that the connection is reading the right Stripe data before any operation changes state.
Use this order:
- Confirm the account and test mode in Stripe.
- Retrieve the expected customer record.
- Retrieve the expected product record.
- Compare the results with the records you intended to inspect.
- Record any mismatch as a connection or permission issue.
MCP separates the client from the server and the underlying service, so a successful tool response still needs contextual review. The MCP architecture documentation explains that interaction model. For practical security guidance, see what actually matters in MCP security.
How do you gate payments, refunds, and subscription changes?
Gate payment, refund, customer, and subscription writes behind an explicit review of the Stripe account, mode, target record, credential scope, and requested action. Allow the write only after the read pass confirms the intended test context.
Use a short approval sequence:
- Pause after the customer and product reads.
- Review the account and mode in Stripe.
- Confirm that the credential is restricted and intended for test use.
- Check the exact target and action shown by the client.
- Approve only the single consequential operation you intend to perform.
- Recheck the resulting Stripe state before starting another write.
The user must review the account and mode before consequential payment operations. An MCP client confirmation is not a substitute for Stripe-side restrictions, and a confirmation prompt does not make a live credential equivalent to a test credential.
Keep refunds and subscription changes behind the same gate as payments. They may affect existing records and should not be enabled merely because an earlier read succeeded. The MCP security best-practices specification is a useful reference for keeping authorization and permission decisions explicit.
How do you fix mode, account, permission, and missing-tool errors?
Fix errors by checking the account and mode first, then the credential scope and explicit tool selection. Treat a missing tool as a configuration issue to investigate, not as a reason to expose every available tool.
| Symptom | Check first | Corrective action |
|---|---|---|
| Data appears to be live | Stripe account and mode | Stop, switch to the intended test context, and reconnect |
| Permission denied | Restricted key scope | Adjust the test credential only as needed |
| Expected tool is missing | Explicit tool selection | Add only the required tool, not the full surface |
| Unexpected account appears | OAuth account selection or local key | Re-authenticate or replace the test credential |
| Read result is unexpected | Account, mode, and target record | Stop before any write and repeat the read check |
For local setup, remember that @stripe/mcp accepts an API key and explicit tools. If you used --tools=all, narrow the selection before continuing. For hosted OAuth, review which Stripe account was authorized and whether it is the intended test context.
If the same error remains, return to the official Stripe collection and compare the connection path with Stripe’s current MCP and Agent Toolkit documentation. Do not disable authentication, TLS, or permission checks to make the connection proceed.