# How to integrate Stripe MCP with Pydantic AI ```json { "title": "How to integrate Stripe MCP with Pydantic AI", "toolkit": "Stripe", "toolkit_slug": "stripe", "framework": "Pydantic AI", "framework_slug": "pydantic-ai", "url": "https://composio.dev/toolkits/stripe/framework/pydantic-ai", "markdown_url": "https://composio.dev/toolkits/stripe/framework/pydantic-ai.md", "updated_at": "2026-05-06T08:30:09.639Z" } ``` ## Introduction This guide walks you through connecting Stripe to Pydantic AI using the Composio tool router. By the end, you'll have a working Stripe agent that can create a new stripe customer with email, generate a draft invoice for recent orders, cancel an active subscription at period end through natural language commands. This guide will help you understand how to give your Pydantic AI agent real control over a Stripe account through Composio's Stripe MCP server. Before we dive in, let's take a quick look at the key ideas and tools involved. ## Also integrate Stripe with - [ChatGPT](https://composio.dev/toolkits/stripe/framework/chatgpt) - [OpenAI Agents SDK](https://composio.dev/toolkits/stripe/framework/open-ai-agents-sdk) - [Claude Agent SDK](https://composio.dev/toolkits/stripe/framework/claude-agents-sdk) - [Claude Code](https://composio.dev/toolkits/stripe/framework/claude-code) - [Claude Cowork](https://composio.dev/toolkits/stripe/framework/claude-cowork) - [Codex](https://composio.dev/toolkits/stripe/framework/codex) - [Cursor](https://composio.dev/toolkits/stripe/framework/cursor) - [VS Code](https://composio.dev/toolkits/stripe/framework/vscode) - [OpenCode](https://composio.dev/toolkits/stripe/framework/opencode) - [OpenClaw](https://composio.dev/toolkits/stripe/framework/openclaw) - [Hermes](https://composio.dev/toolkits/stripe/framework/hermes-agent) - [CLI](https://composio.dev/toolkits/stripe/framework/cli) - [Google ADK](https://composio.dev/toolkits/stripe/framework/google-adk) - [LangChain](https://composio.dev/toolkits/stripe/framework/langchain) - [Vercel AI SDK](https://composio.dev/toolkits/stripe/framework/ai-sdk) - [Mastra AI](https://composio.dev/toolkits/stripe/framework/mastra-ai) - [LlamaIndex](https://composio.dev/toolkits/stripe/framework/llama-index) - [CrewAI](https://composio.dev/toolkits/stripe/framework/crew-ai) ## TL;DR Here's what you'll learn: - How to set up your Composio API key and User ID - How to create a Composio Tool Router session for Stripe - How to attach an MCP Server to a Pydantic AI agent - How to stream responses and maintain chat history - How to build a simple REPL-style chat interface to test your Stripe workflows ## What is Pydantic AI? Pydantic AI is a Python framework for building AI agents with strong typing and validation. It leverages Pydantic's data validation capabilities to create robust, type-safe AI applications. Key features include: - Type Safety: Built on Pydantic for automatic data validation - MCP Support: Native support for Model Context Protocol servers - Streaming: Built-in support for streaming responses - Async First: Designed for async/await patterns ## What is the Stripe MCP server, and what's possible with it? The Stripe MCP server is an implementation of the Model Context Protocol that connects your AI agent and assistants like Claude, Cursor, etc directly to your Stripe account. It provides structured and secure access to your payments platform, so your agent can perform actions like creating customers, managing subscriptions, issuing refunds, and generating invoices on your behalf. - Automated customer management: Effortlessly create, update, or delete Stripe customers—enabling streamlined onboarding and account maintenance through your agent. - Subscription and recurring billing automation: Have your agent create, configure, or cancel subscriptions, supporting trials, discounts, and advanced billing scenarios with ease. - Smart payment and refund processing: Allow your agent to initiate payment intents, confirm transactions, and issue full or partial refunds as needed, all through secure APIs. - Seamless invoice and price creation: Generate draft invoices for customers, create new products, and set up pricing structures—saving you time on manual billing tasks. - Advanced product and pricing management: Let your agent create new products and prices, helping you roll out new offerings or adjust monetization strategies with just a prompt. ## Supported Tools | Tool slug | Name | Description | |---|---|---| | `STRIPE_CANCEL_SUBSCRIPTION` | Cancel subscription | Cancels a customer's active stripe subscription at the end of the current billing period, with options to invoice immediately for metered usage and prorate charges for unused time. | | `STRIPE_CONFIRM_PAYMENT_INTENT` | Confirm payment intent | Confirms a stripe paymentintent to finalize a payment; a `return url` is necessary if the payment method requires customer redirection. | | `STRIPE_CREATE_CUSTOMER` | Create Customer | Creates a new customer in stripe, required for creating charges or subscriptions; an email is highly recommended for customer communications. | | `STRIPE_CREATE_INVOICE` | Create an invoice | Creates a new draft stripe invoice for a customer; use to revise an existing invoice, bill for a specific subscription (which must belong to the customer), or apply detailed customizations. | | `STRIPE_CREATE_PAYMENT_INTENT` | Create payment intent | Creates a stripe paymentintent to initiate and process a customer's payment; using `application fee amount` for a connected account requires the `stripe-account` header. | | `STRIPE_CREATE_PRICE` | Create a price | Creates a new stripe price for a product, defining its charges (one-time or recurring) and billing scheme; requires either an existing `product` id or `product data`. | | `STRIPE_CREATE_PRODUCT` | Create product | Creates a new product in stripe, encoding the request as `application/x-www-form-urlencoded` by flattening nested structures. | | `STRIPE_CREATE_REFUND` | Create Refund | Creates a full or partial refund in stripe, targeting either a specific charge id or a payment intent id. | | `STRIPE_CREATE_SUBSCRIPTION` | Create subscription | Creates a new, highly configurable subscription for an existing stripe customer, supporting multiple items, trials, discounts, and various billing/payment options. | | `STRIPE_DELETE_CUSTOMER` | Delete customer | Permanently deletes an existing stripe customer; this irreversible action also cancels their active subscriptions and removes all associated data. | | `STRIPE_LIST_CHARGES` | List Charges | Retrieves a list of stripe charges with filtering and pagination; use valid cursor ids from previous responses for pagination, and note that charges are typically returned in reverse chronological order. | | `STRIPE_LIST_COUPONS` | List Stripe coupons | Retrieves a list of discount coupons from a stripe account, supporting pagination via `limit`, `starting after`, and `ending before`. | | `STRIPE_LIST_CUSTOMER_PAYMENT_METHODS` | List customer payment methods | Retrieves a list of payment methods for a given customer, supporting type filtering and pagination. | | `STRIPE_LIST_CUSTOMERS` | List customers | Retrieves a list of stripe customers, with options to filter by email, creation date, or test clock, and support for pagination. | | `STRIPE_LIST_INVOICES` | List Invoices | Retrieves a list of stripe invoices, filterable by various criteria and paginatable using invoice id cursors obtained from previous responses. | | `STRIPE_LIST_PAYMENT_INTENTS` | List payment intents | Retrieves a list of stripe paymentintents, optionally filtered and paginated using paymentintent ids as cursors. | | `STRIPE_LIST_PAYMENT_LINKS` | List payment links | Retrieves a list of payment links from stripe, sorted by creation date in descending order by default. | | `STRIPE_LIST_PRODUCTS` | List products | Retrieves a list of stripe products, with optional filtering and pagination; `starting after`/`ending before` cursors must be valid product ids from a previous response. | | `STRIPE_LIST_REFUNDS` | List Refunds | Lists stripe refunds, sorted by creation date descending (newest first), with optional filtering by charge or payment intent and pagination support. | | `STRIPE_LIST_SHIPPING_RATES` | List Stripe shipping rates | Retrieves a list of stripe shipping rates, filterable by active status, creation date, and currency; useful for managing or displaying shipping options. | | `STRIPE_LIST_SUBSCRIPTIONS` | List subscriptions | Retrieves a list of stripe subscriptions, optionally filtered by various criteria such as customer, price, status, collection method, and date ranges, with support for pagination. | | `STRIPE_LIST_TAX_CODES` | List tax codes | Retrieves a paginated list of globally available, predefined stripe tax codes used for classifying products and services in stripe tax. | | `STRIPE_LIST_TAX_RATES` | List tax rates | Retrieves a list of tax rates, which are returned sorted by creation date in descending order. | | `STRIPE_RETRIEVE_BALANCE` | Retrieve Balance | Retrieves the complete current balance details for the connected stripe account. | | `STRIPE_RETRIEVE_CHARGE` | Retrieve Charge Details | Retrieves full details for an existing stripe charge using its unique id. | | `STRIPE_RETRIEVE_CUSTOMER` | Retrieve customer | Retrieves detailed information for an existing stripe customer using their unique customer id. | | `STRIPE_RETRIEVE_PAYMENT_INTENT` | Retrieve payment intent | Retrieves a paymentintent by its id; `client secret` is required if a publishable api key is used. | | `STRIPE_RETRIEVE_REFUND` | Retrieve a refund | Retrieves details for an existing stripe refund using its unique `refund id`. | | `STRIPE_RETRIEVE_SUBSCRIPTION` | Retrieve subscription | Retrieves detailed information for an existing stripe subscription using its unique id. | | `STRIPE_SEARCH_CUSTOMERS` | Search Stripe customers | Retrieves a list of stripe customers matching a search query that adheres to stripe's search query language. | | `STRIPE_UPDATE_CUSTOMER` | Update Customer | Updates an existing stripe customer, identified by customer id, with only the provided details; unspecified fields remain unchanged. | | `STRIPE_UPDATE_PAYMENT_INTENT` | Update Payment Intent | Updates a stripe paymentintent with new values for specified parameters; note that if `currency` is updated, `amount` might also be required, and certain updates (e.g., to `payment method`) can necessitate re-confirmation by the customer. | | `STRIPE_UPDATE_SUBSCRIPTION` | Update Subscription | Updates an existing, non-canceled stripe subscription by its id, ensuring all referenced entity ids (e.g., prices, coupons) are valid and automatic tax liability is correctly specified if enabled. | ## Supported Triggers | Trigger slug | Name | Description | |---|---|---| | `STRIPE_CHARGE_FAILED_TRIGGER` | Charge Failed Trigger | Triggered when a direct charge fails in Stripe's legacy Charges API | | `STRIPE_CHECKOUT_SESSION_COMPLETED_TRIGGER` | Checkout Session Completed Trigger | Triggered when a checkout session is completed in Stripe | | `STRIPE_INVOICE_PAYMENT_SUCCEEDED_TRIGGER` | Invoice Payment Succeeded Trigger | Triggered when an invoice payment is successful in Stripe | | `STRIPE_PAYMENT_FAILED_TRIGGER` | Payment Intent Failed Trigger | Triggered when a payment intent fails in Stripe | | `STRIPE_PRODUCT_CREATED_TRIGGER` | Product Created Trigger | Triggered when a product is created in Stripe | | `STRIPE_SUBSCRIPTION_ADDED_TRIGGER` | Subscription Added Trigger | Triggered when a subscription is added in Stripe | | `STRIPE_SUBSCRIPTION_DELETED_TRIGGER` | Subscription Deleted Trigger | Triggered when a subscription is deleted in Stripe | ## Creating MCP Server - Stand-alone vs Composio SDK The Stripe MCP server is an implementation of the Model Context Protocol that connects your AI agent to Stripe. It provides structured and secure access so your agent can perform Stripe operations on your behalf through a secure, permission-based interface. With Composio's managed implementation, you don't have to create your own developer app. For production, if you're building an end product, we recommend using your own credentials. The managed server helps you prototype fast and go from 0-1 faster. ## Step-by-step Guide ### 1. Prerequisites Before starting, make sure you have: - Python 3.9 or higher - A Composio account with an active API key - Basic familiarity with Python and async programming ### 1. Getting API Keys for OpenAI and Composio OpenAI API Key - Go to the [OpenAI dashboard](https://platform.openai.com/settings/organization/api-keys) and create an API key. You'll need credits to use the models, or you can connect to another model provider. - Keep the API key safe. Composio API Key - Log in to the [Composio dashboard](https://dashboard.composio.dev?utm_source=toolkits&utm_medium=framework_docs). - Navigate to your API settings and generate a new API key. - Store this key securely as you'll need it for authentication. ### 2. Install dependencies Install the required libraries. What's happening: - composio connects your agent to external SaaS tools like Stripe - pydantic-ai lets you create structured AI agents with tool support - python-dotenv loads your environment variables securely from a .env file ```bash pip install composio pydantic-ai python-dotenv ``` ### 3. Set up environment variables Create a .env file in your project root. What's happening: - COMPOSIO_API_KEY authenticates your agent to Composio's API - USER_ID associates your session with your account for secure tool access - OPENAI_API_KEY to access OpenAI LLMs ```bash COMPOSIO_API_KEY=your_composio_api_key_here USER_ID=your_user_id_here OPENAI_API_KEY=your_openai_api_key ``` ### 4. Import dependencies What's happening: - We load environment variables and import required modules - Composio manages connections to Stripe - MCPServerStreamableHTTP connects to the Stripe MCP server endpoint - Agent from Pydantic AI lets you define and run the AI assistant ```python import asyncio import os from dotenv import load_dotenv from composio import Composio from pydantic_ai import Agent from pydantic_ai.mcp import MCPServerStreamableHTTP load_dotenv() ``` ### 5. Create a Tool Router Session What's happening: - We're creating a Tool Router session that gives your agent access to Stripe tools - The create method takes the user ID and specifies which toolkits should be available - The returned session.mcp.url is the MCP server URL that your agent will use ```python async def main(): api_key = os.getenv("COMPOSIO_API_KEY") user_id = os.getenv("USER_ID") if not api_key or not user_id: raise RuntimeError("Set COMPOSIO_API_KEY and USER_ID in your environment") # Create a Composio Tool Router session for Stripe composio = Composio(api_key=api_key) session = composio.create( user_id=user_id, toolkits=["stripe"], ) url = session.mcp.url if not url: raise ValueError("Composio session did not return an MCP URL") ``` ### 6. Initialize the Pydantic AI Agent What's happening: - The MCP client connects to the Stripe endpoint - The agent uses GPT-5 to interpret user commands and perform Stripe operations - The instructions field defines the agent's role and behavior ```python # Attach the MCP server to a Pydantic AI Agent stripe_mcp = MCPServerStreamableHTTP(url, headers={"x-api-key": COMPOSIO_API_KEY}) agent = Agent( "openai:gpt-5", toolsets=[stripe_mcp], instructions=( "You are a Stripe assistant. Use Stripe tools to help users " "with their requests. Ask clarifying questions when needed." ), ) ``` ### 7. Build the chat interface What's happening: - The agent reads input from the terminal and streams its response - Stripe API calls happen automatically under the hood - The model keeps conversation history to maintain context across turns ```python # Simple REPL with message history history = [] print("Chat started! Type 'exit' or 'quit' to end.\n") print("Try asking the agent to help you with Stripe.\n") while True: user_input = input("You: ").strip() if user_input.lower() in {"exit", "quit", "bye"}: print("\nGoodbye!") break if not user_input: continue print("\nAgent is thinking...\n", flush=True) async with agent.run_stream(user_input, message_history=history) as stream_result: collected_text = "" async for chunk in stream_result.stream_output(): text_piece = None if isinstance(chunk, str): text_piece = chunk elif hasattr(chunk, "delta") and isinstance(chunk.delta, str): text_piece = chunk.delta elif hasattr(chunk, "text"): text_piece = chunk.text if text_piece: collected_text += text_piece result = stream_result print(f"Agent: {collected_text}\n") history = result.all_messages() ``` ### 8. Run the application What's happening: - The asyncio loop launches the agent and keeps it running until you exit ```python if __name__ == "__main__": asyncio.run(main()) ``` ## Complete Code ```python import asyncio import os from dotenv import load_dotenv from composio import Composio from pydantic_ai import Agent from pydantic_ai.mcp import MCPServerStreamableHTTP load_dotenv() async def main(): api_key = os.getenv("COMPOSIO_API_KEY") user_id = os.getenv("USER_ID") if not api_key or not user_id: raise RuntimeError("Set COMPOSIO_API_KEY and USER_ID in your environment") # Create a Composio Tool Router session for Stripe composio = Composio(api_key=api_key) session = composio.create( user_id=user_id, toolkits=["stripe"], ) url = session.mcp.url if not url: raise ValueError("Composio session did not return an MCP URL") # Attach the MCP server to a Pydantic AI Agent stripe_mcp = MCPServerStreamableHTTP(url, headers={"x-api-key": COMPOSIO_API_KEY}) agent = Agent( "openai:gpt-5", toolsets=[stripe_mcp], instructions=( "You are a Stripe assistant. Use Stripe tools to help users " "with their requests. Ask clarifying questions when needed." ), ) # Simple REPL with message history history = [] print("Chat started! Type 'exit' or 'quit' to end.\n") print("Try asking the agent to help you with Stripe.\n") while True: user_input = input("You: ").strip() if user_input.lower() in {"exit", "quit", "bye"}: print("\nGoodbye!") break if not user_input: continue print("\nAgent is thinking...\n", flush=True) async with agent.run_stream(user_input, message_history=history) as stream_result: collected_text = "" async for chunk in stream_result.stream_output(): text_piece = None if isinstance(chunk, str): text_piece = chunk elif hasattr(chunk, "delta") and isinstance(chunk.delta, str): text_piece = chunk.delta elif hasattr(chunk, "text"): text_piece = chunk.text if text_piece: collected_text += text_piece result = stream_result print(f"Agent: {collected_text}\n") history = result.all_messages() if __name__ == "__main__": asyncio.run(main()) ``` ## Conclusion You've built a Pydantic AI agent that can interact with Stripe through Composio's Tool Router. With this setup, your agent can perform real Stripe actions through natural language. You can extend this further by: - Adding other toolkits like Gmail, HubSpot, or Salesforce - Building a web-based chat interface around this agent - Using multiple MCP endpoints to enable cross-app workflows (for example, Gmail + Stripe for workflow automation) This architecture makes your AI agent "agent-native", able to securely use APIs in a unified, composable way without custom integrations. ## How to build Stripe MCP Agent with another framework - [ChatGPT](https://composio.dev/toolkits/stripe/framework/chatgpt) - [OpenAI Agents SDK](https://composio.dev/toolkits/stripe/framework/open-ai-agents-sdk) - [Claude Agent SDK](https://composio.dev/toolkits/stripe/framework/claude-agents-sdk) - [Claude Code](https://composio.dev/toolkits/stripe/framework/claude-code) - [Claude Cowork](https://composio.dev/toolkits/stripe/framework/claude-cowork) - [Codex](https://composio.dev/toolkits/stripe/framework/codex) - [Cursor](https://composio.dev/toolkits/stripe/framework/cursor) - [VS Code](https://composio.dev/toolkits/stripe/framework/vscode) - [OpenCode](https://composio.dev/toolkits/stripe/framework/opencode) - [OpenClaw](https://composio.dev/toolkits/stripe/framework/openclaw) - [Hermes](https://composio.dev/toolkits/stripe/framework/hermes-agent) - [CLI](https://composio.dev/toolkits/stripe/framework/cli) - [Google ADK](https://composio.dev/toolkits/stripe/framework/google-adk) - [LangChain](https://composio.dev/toolkits/stripe/framework/langchain) - [Vercel AI SDK](https://composio.dev/toolkits/stripe/framework/ai-sdk) - [Mastra AI](https://composio.dev/toolkits/stripe/framework/mastra-ai) - [LlamaIndex](https://composio.dev/toolkits/stripe/framework/llama-index) - [CrewAI](https://composio.dev/toolkits/stripe/framework/crew-ai) ## Related Toolkits - [Alpha vantage](https://composio.dev/toolkits/alpha_vantage) - Alpha Vantage is a financial data platform offering real-time and historical stock market APIs. Get instant, reliable access to equities, forex, and technical analysis data for smarter trading decisions. - [Altoviz](https://composio.dev/toolkits/altoviz) - Altoviz is a cloud-based billing and invoicing platform for businesses. It streamlines online payments, expense tracking, and customizable invoice management. - [Benzinga](https://composio.dev/toolkits/benzinga) - Benzinga provides real-time financial news and data APIs for market coverage. It helps you track breaking news and actionable market insights instantly. - [Brex](https://composio.dev/toolkits/brex) - Brex provides corporate credit cards and spend management tailored for startups and tech businesses. It helps optimize company cash flow, streamline accounting, and accelerate business growth. - [Chaser](https://composio.dev/toolkits/chaser) - Chaser is accounts receivable automation software that sends invoice reminders and helps businesses get paid faster. It streamlines the collections process to save time and improve cash flow. - [Clientary](https://composio.dev/toolkits/clientary) - Clientary is a platform for managing clients, invoices, projects, proposals, and more. It streamlines client work and saves you serious admin time. - [Coinbase](https://composio.dev/toolkits/coinbase) - Coinbase is a platform for buying, selling, and storing cryptocurrency. It makes exchanging and managing crypto simple and secure for everyone. - [Coinranking](https://composio.dev/toolkits/coinranking) - Coinranking is a comprehensive cryptocurrency market data platform offering access to real-time coin prices, market caps, and historical data. Get accurate, up-to-date stats for thousands of digital assets in one place. - [Coupa](https://composio.dev/toolkits/coupa) - Coupa is a business spend management platform for procurement, invoicing, and expenses. It helps organizations streamline purchasing, control costs, and gain complete visibility over financial operations. - [CurrencyScoop](https://composio.dev/toolkits/currencyscoop) - CurrencyScoop is a developer-friendly API for real-time and historical currency exchange rates. Easily access fiat and crypto data for smart, up-to-date financial applications. - [Daffy](https://composio.dev/toolkits/daffy) - Daffy is a modern charitable giving platform with a donor-advised fund. Easily set aside funds, grow them tax-free, and donate to over 1.7 million U.S. charities. - [Eagle doc](https://composio.dev/toolkits/eagle_doc) - Eagle doc is an AI-powered OCR API for invoices and receipts. It delivers fast, reliable, and accurate document data extraction for seamless automation. - [Elorus](https://composio.dev/toolkits/elorus) - Elorus is an online invoicing and time-tracking software for freelancers and small businesses. Easily manage finances, bill clients, and track work in one place. - [Eodhd apis](https://composio.dev/toolkits/eodhd_apis) - Eodhd apis delivers comprehensive financial data, including live and historical stock prices, via robust APIs. Easily access reliable, up-to-date market insights to power your apps, dashboards, and analytics. - [Fidel api](https://composio.dev/toolkits/fidel_api) - Fidel api is a secure platform for linking payment cards to web and mobile apps. It enables real-time card transaction monitoring and event-based automation for businesses. - [Finage](https://composio.dev/toolkits/finage) - Finage is a secure API platform delivering real-time and historical financial data for stocks, forex, crypto, indices, and commodities. It empowers developers and businesses to access, analyze, and act on market data instantly. - [Finmei](https://composio.dev/toolkits/finmei) - Finmei is an invoicing tool that simplifies billing, invoice management, and expense tracking. Ideal for automating and organizing your business finances in one place. - [Fixer](https://composio.dev/toolkits/fixer) - Fixer is a currency data API offering real-time and historical exchange rates for 170 currencies. Instantly access accurate, up-to-date forex data for your applications and workflows. - [Fixer io](https://composio.dev/toolkits/fixer_io) - Fixer.io is a lightweight API for real-time and historical foreign exchange rates. It makes global currency conversion fast, accurate, and hassle-free. - [Flutterwave](https://composio.dev/toolkits/flutterwave) - Flutterwave is a global payments platform enabling businesses to accept and send payments across Africa and beyond. Its robust APIs simplify cross-border transactions and financial operations. ## Frequently Asked Questions ### What are the differences in Tool Router MCP and Stripe MCP? With a standalone Stripe MCP server, the agents and LLMs can only access a fixed set of Stripe tools tied to that server. However, with the Composio Tool Router, agents can dynamically load tools from Stripe and many other apps based on the task at hand, all through a single MCP endpoint. ### Can I use Tool Router MCP with Pydantic AI? Yes, you can. Pydantic AI fully supports MCP integration. You get structured tool calling, message history handling, and model orchestration while Tool Router takes care of discovering and serving the right Stripe tools. ### Can I manage the permissions and scopes for Stripe while using Tool Router? Yes, absolutely. You can configure which Stripe scopes and actions are allowed when connecting your account to Composio. You can also bring your own OAuth credentials or API configuration so you keep full control over what the agent can do. ### How safe is my data with Composio Tool Router? All sensitive data such as tokens, keys, and configuration is fully encrypted at rest and in transit. Composio is SOC 2 Type 2 compliant and follows strict security practices so your Stripe data and credentials are handled as safely as possible. --- [See all toolkits](https://composio.dev/toolkits) · [Composio docs](https://docs.composio.dev/llms.txt)