stripe__ai/tools/python/MIGRATION.md

# Migration Guide: API to MCP Architecture

This guide covers migrating from the direct API-based toolkit (v0.6.x) to the MCP-based architecture (v0.7.0+).

## Breaking Changes

### 1. Async Initialization Required

Toolkit initialization now connects to `mcp.stripe.com` and must be awaited.

```python
# Before (v0.6.x)
from stripe_agent_toolkit.openai.toolkit import StripeAgentToolkit

toolkit = StripeAgentToolkit(secret_key="sk_test_...", configuration={...})
tools = toolkit.tools

# After (v0.7.0+)
from stripe_agent_toolkit.openai.toolkit import create_stripe_agent_toolkit

toolkit = await create_stripe_agent_toolkit(secret_key="rk_test_...")
tools = toolkit.get_tools()
await toolkit.close()  # Clean up when done
```

**Impact:** Synchronous usage will throw: `"StripeAgentToolkit not initialized. Call await toolkit.initialize() first."`

### 2. MCP Connection Required

Tools are fetched from `mcp.stripe.com`. If the server is unreachable, initialization fails with no fallback.

**Impact:** Ensure network access to `mcp.stripe.com` (HTTPS port 443) in all environments.

### 3. Tool Names Changed to snake_case

| Old                 | New                   |
| ------------------- | --------------------- |
| `createCustomer`    | `create_customer`     |
| `listCustomers`     | `list_customers`      |
| `createPaymentLink` | `create_payment_link` |

**Impact:** Update any custom tool filtering logic to use snake_case.

### 4. `mcp` Package Now Required

The `mcp` package is now a required dependency:

```bash
pip install stripe-agent-toolkit>=0.7.0
```

### 5. `actions` Configuration Removed

The `configuration.actions` option has been removed. Tool permissions are now controlled entirely by your Restricted API Key (RAK) on the server side.

```python
# Before (v0.6.x)
toolkit = StripeAgentToolkit(
    secret_key="rk_test_...",
    configuration={
        "actions": {
            "customers": {"create": True, "read": True},
            "invoices": {"create": True},
        },
    },
)

# After (v0.7.0+)
toolkit = await create_stripe_agent_toolkit(
    secret_key="rk_test_...",  # RAK permissions control which tools are available
    configuration={
        "context": {"account": "acct_123"},  # Only context options remain
    },
)
```

**Impact:** Remove any `actions` from your configuration. Configure permissions when creating your Restricted API Key in the Stripe Dashboard instead.

---

## New API

There are two ways to initialize the toolkit. Both are valid—choose whichever fits your code structure better.

### Option 1: Factory Function (Recommended)

The simplest approach. Creates and initializes the toolkit in one step:

```python
from stripe_agent_toolkit.openai.toolkit import create_stripe_agent_toolkit
# Also available: .langchain.toolkit, .crewai.toolkit, .strands.toolkit

async def main():
    toolkit = await create_stripe_agent_toolkit(secret_key="rk_test_...")
    try:
        tools = toolkit.get_tools()
        # ... use tools ...
    finally:
        await toolkit.close()
```

### Option 2: Constructor + initialize()

If you need to create the toolkit instance separately from initialization (e.g., for dependency injection or delayed initialization):

```python
from stripe_agent_toolkit.openai.toolkit import StripeAgentToolkit

toolkit = StripeAgentToolkit(secret_key="rk_test_...")

# Later, when ready to use:
async def main():
    await toolkit.initialize()
    try:
        tools = toolkit.get_tools()
        # ... use tools ...
    finally:
        await toolkit.close()
```

### Cleanup

Always close the MCP connection when done:

```python
await toolkit.close()
```

---

## Framework-Specific Examples

### OpenAI Agents SDK

```python
import asyncio
from agents import Agent, Runner
from stripe_agent_toolkit.openai.toolkit import create_stripe_agent_toolkit

async def main():
    toolkit = await create_stripe_agent_toolkit(secret_key="rk_test_...")

    try:
        agent = Agent(
            name="Stripe Agent",
            tools=toolkit.get_tools(),
        )
        result = await Runner.run(agent, "Create a customer with email test@example.com")
        print(result.final_output)
    finally:
        await toolkit.close()

asyncio.run(main())
```

### LangChain

```python
import asyncio
from langchain_openai import ChatOpenAI
from langgraph.prebuilt import create_react_agent
from stripe_agent_toolkit.langchain.toolkit import create_stripe_agent_toolkit

async def main():
    toolkit = await create_stripe_agent_toolkit(secret_key="rk_test_...")

    try:
        llm = ChatOpenAI(model="gpt-4o")
        agent = create_react_agent(llm, toolkit.get_tools())
        result = agent.invoke({"messages": "Create a payment link for $50"})
        print(result["messages"][-1].content)
    finally:
        await toolkit.close()

asyncio.run(main())
```

### CrewAI

```python
import asyncio
from crewai import Agent, Task, Crew
from stripe_agent_toolkit.crewai.toolkit import create_stripe_agent_toolkit

async def main():
    toolkit = await create_stripe_agent_toolkit(secret_key="rk_test_...")

    try:
        agent = Agent(
            role="Stripe Agent",
            goal="Create Stripe products",
            tools=toolkit.get_tools(),
        )
        task = Task(description="Create a product", agent=agent)
        crew = Crew(agents=[agent], tasks=[task])
        crew.kickoff()
    finally:
        await toolkit.close()

asyncio.run(main())
```

### Strands

```python
import asyncio
from strands import Agent
from stripe_agent_toolkit.strands.toolkit import create_stripe_agent_toolkit

async def main():
    toolkit = await create_stripe_agent_toolkit(secret_key="rk_test_...")

    try:
        agent = Agent(tools=toolkit.get_tools())
        response = agent("Create a payment link for $25")
        print(response)
    finally:
        await toolkit.close()

asyncio.run(main())
```

---

## Other Changes

### Restricted Keys Recommended

We strongly recommend using restricted keys (`rk_*`) instead of `sk_*` keys for better security and granular permissions. Tool availability is determined by your RAK's permissions on the server.

Create restricted keys at: https://dashboard.stripe.com/apikeys

---

## Migration Checklist

- [ ] Use `create_stripe_agent_toolkit()` factory function with `await`
- [ ] Add error handling for MCP connection failures
- [ ] Ensure `mcp.stripe.com` is accessible in all environments
- [ ] Update tool name filters to snake_case
- [ ] Add `await toolkit.close()` for cleanup (use try/finally)
- [ ] Remove `configuration.actions` and configure permissions via Restricted API Key instead
- [ ] Switch to restricted keys (`rk_*`) for production use

## Troubleshooting

### Connection Errors

If you see `Failed to connect to Stripe MCP server`:
1. Check network connectivity to `mcp.stripe.com`
2. Verify your API key is valid
3. Ensure firewall allows HTTPS (port 443) outbound

### "Not initialized" Errors

If you see `StripeAgentToolkit not initialized`:
- Make sure you're using `await create_stripe_agent_toolkit()`
- Or call `await toolkit.initialize()` after creating the toolkit

### Key Recommendation Warnings

If you see warnings about API keys:
- Switch from `StripeAgentToolkit()` to `create_stripe_agent_toolkit()`
- Switch from `sk_*` keys to `rk_*` restricted keys for better security

## Getting Help

- GitHub Issues: https://github.com/stripe/agent-toolkit/issues
- Stripe Documentation: https://docs.stripe.com/agent-toolkit