TL;DR:

  • Stripe’s Agent Toolkit exposes payment operations as MCP-compatible tools, letting agents create invoices, retrieve customer data, and manage subscriptions without custom API wrappers.
  • The toolkit ships with LangChain and OpenAI Agents SDK integrations out of the box, with a framework-agnostic MCP server option for everything else.
  • Production use requires scoped API keys, explicit allowlisting of which tools the agent can use, and human-in-the-loop approval for any write operation involving real money.

Most agent frameworks give you excellent tools for reading and transforming data. Actually doing something with money — creating an invoice, issuing a refund, cancelling a subscription — has traditionally required custom code: authenticate, construct the right Stripe API call, handle the response, map errors to something the agent can reason about. The Stripe Agent Toolkit eliminates most of that plumbing.

What the Toolkit Is

Stripe released its official Agent Toolkit as an open-source package (@stripe/agent-toolkit) that wraps Stripe’s API as a set of structured tools suitable for use with LLM agent frameworks. The tools are described in a way that LLMs can reason about — with clear names, parameter schemas, and return formats — and the toolkit handles the actual API calls.

The core tools cover the operations that agents most commonly need:

  • Customer operations: retrieve customer, create customer, list customers
  • Invoice operations: create invoice, retrieve invoice, list invoices, finalise invoice, send invoice
  • Payment intent operations: create payment intent, retrieve payment intent
  • Subscription operations: retrieve subscription, update subscription, cancel subscription
  • Product and price operations: create product, create price, retrieve price
  • Refund operations: create refund

Each tool maps directly to a Stripe API endpoint, and the toolkit handles pagination, error formatting, and response normalisation.

Installation and Setup

npm install @stripe/agent-toolkit

The toolkit requires a Stripe API key. For agent use, create a restricted key in the Stripe dashboard with only the permissions the agent actually needs — not a full secret key. If the agent only creates invoices, the key should only have invoices:write and customers:read.

Using with OpenAI Agents SDK

import Stripe from 'stripe';
import { StripeAgentToolkit } from '@stripe/agent-toolkit/openai';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);

const toolkit = new StripeAgentToolkit({
  secretKey: process.env.STRIPE_SECRET_KEY!,
  configuration: {
    actions: {
      paymentLinks: { create: true },
      invoices: { create: true, update: false },
      customers: { read: true, create: false },
      subscriptions: { read: true, update: false, cancel: false },
      products: { read: true },
      prices: { read: true },
      // Refunds explicitly disabled for this agent
      refunds: { create: false },
    },
  },
});

// Get tools in OpenAI format
const tools = toolkit.getTools();

// Use with OpenAI Agents SDK
import { Agent } from '@openai/agents';

const billingAgent = new Agent({
  name: 'billing-assistant',
  instructions: `You are a billing assistant that helps customers understand their invoices 
  and account status. You can look up customer records and invoices. 
  You cannot modify subscriptions or issue refunds without human approval.`,
  tools: tools,
});

The configuration.actions object is the most important production consideration: it defines precisely what the agent can do. An invoice-creation agent should not have refund creation enabled. A read-only customer support agent should have all write operations disabled.

Using with LangChain

from stripe_agent_toolkit.langchain.toolkit import StripeAgentToolkit
from langchain.agents import AgentExecutor, create_openai_tools_agent
from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate

toolkit = StripeAgentToolkit(
    secret_key=os.environ["STRIPE_SECRET_KEY"],
    configuration={
        "actions": {
            "customers": {"read": True, "create": False},
            "invoices": {"read": True, "create": True, "update": False},
            "subscriptions": {"read": True},
            "refunds": {"create": False},
        }
    }
)

tools = toolkit.get_tools()

llm = ChatOpenAI(model="gpt-4o", temperature=0)
prompt = ChatPromptTemplate.from_messages([
    ("system", "You are a billing assistant. Help users understand their account status."),
    ("placeholder", "{chat_history}"),
    ("human", "{input}"),
    ("placeholder", "{agent_scratchpad}"),
])

agent = create_openai_tools_agent(llm, tools, prompt)
agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True)

MCP Server Mode (Framework-Agnostic)

If you’re using a framework that supports MCP natively — or you want to expose Stripe tools to multiple agents — the toolkit can run as a standalone MCP server:

npx @stripe/mcp --api-key=sk_live_... --tools=create_invoice,get_customer

This exposes the Stripe tools via the MCP protocol. Claude, Cursor, and any other MCP-compatible client can then use them directly. The --tools flag restricts which operations are exposed — always use it; never run the MCP server with all tools enabled unless you have strong justification.

Production Considerations

API key scoping is non-negotiable. A restricted Stripe key with only the permissions your agent needs is the most important security control. Stripe’s dashboard supports granular per-object-type read/write permissions. Create a key specific to each agent role, not a shared key across all agents.

Human-in-the-loop for financial writes. Any agent that creates invoices, processes refunds, or modifies subscriptions should have a human approval step before committing. The cleanest pattern is to have the agent prepare the action (draft invoice, calculate refund amount, propose subscription change) and present it for approval before calling the Stripe API. Use the configuration.actions to disable write access in the initial agent, then route approved actions through a separate restricted execution step.

Test in Stripe test mode first. All agent development should use sk_test_... keys against Stripe’s test environment. Never test write operations against production. The toolkit behaves identically in test mode.

Log all tool calls. Every Stripe API call the agent makes should be logged with the full request and response, linked to the conversation that triggered it. This is essential for audit trails, debugging, and reconstructing what happened when a customer disputes a charge.

Rate limiting. Agents in loops can generate more Stripe API calls than you expect. Stripe has per-second rate limits; implement exponential backoff and ensure your agent doesn’t retry failed calls without limit.

Real Use Cases Where This Shines

Invoice recovery automation. An agent monitors overdue invoices, emails customers personalised reminders, handles replies, and escalates to human collections when needed — all without custom Stripe API integration code.

Billing support chatbots. Customer-facing agents that can answer “what’s on my invoice?” or “when does my subscription renew?” by actually querying Stripe in real time, rather than relying on a CRM that might be out of sync.

Internal billing operations. Internal agents that help finance teams generate bulk invoices, check payment status across large customer lists, or flag anomalous patterns — accessed through Slack or an internal chat interface.

The Stripe Agent Toolkit represents the cleaner direction for agent tooling generally: first-party, opinionated integrations from the API owner rather than hand-rolled wrappers that need maintenance with every API change. The configuration-driven permission system is the right model for production use — explicit allowlisting of what an agent can do, not reliance on prompt instructions to prevent misuse.