straddle

Straddle AI Toolkit

Build payment integrations faster with AI-powered tools for Straddle. Contextual guidance, live API access, and sandbox testing inside your editor.

Prerequisites

Get a Straddle API key from the Straddle Dashboard. Set it as an environment variable:

export STRADDLE_API_KEY="your-api-key-here"

Add this to your shell profile (~/.zshrc, ~/.bashrc, or ~/.config/fish/config.fish) to persist it across sessions.

Setup

Claude Code

Install the plugin. This sets up MCP servers, skills, and slash commands in one step:

claude plugins marketplace add straddleio/ai
claude plugins install straddle

A browser window opens on first use for OAuth. Run /straddle-setup after installing.

Cowork / Claude Desktop

Install the Straddle plugin from the plugin browser. Same plugin as Claude Code.

Cursor

Add the MCP servers to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "straddle": {
      "url": "https://straddle.stlmcp.com/",
      "headers": { "Authorization": "Bearer YOUR_STRADDLE_API_KEY" }
    }
  }
}

Other MCP clients

MCP (Model Context Protocol) connects AI agents to external tools and data sources.

One hosted MCP server:

| Server | URL | Auth | What it provides | |--------|-----|------|------------------| | Straddle API | https://mcp.straddle.com/mcp | OAuth | Code execution, SDK docs search |

For clients that don't support OAuth, use https://straddle.stlmcp.com/ with Authorization: Bearer YOUR_API_KEY instead.

Local MCP

Run the MCP server on your own machine:

npx -y @straddlecom/straddle-mcp@latest --api-key=$STRADDLE_API_KEY

MCP without the plugin (Claude Code)

If you want just the MCP servers without skills and slash commands:

# OAuth (opens browser)
claude mcp add --transport http straddle https://mcp.straddle.com/mcp

# Bearer token (for CI/agents)
claude mcp add --transport http straddle https://straddle.stlmcp.com/ \
  --header "Authorization: Bearer $STRADDLE_API_KEY"

CLI

Full API access from your terminal. Built for developers and AI agents.

brew install straddleio/tools/straddle

# Explore the API
straddle --help
straddle charges create --help

# List customers with structured output
straddle customers list --format json

# Inspect a charge with full HTTP details
straddle charges get ch_123 --debug

# Extract specific fields
straddle customers list --format json --transform 'data.#.{id,name,status}'

Interactive terminal gets styled tables. Piped output switches to JSON automatically.

See CLI docs for the full command reference.

MCP server configuration

Set STRADDLE_ENVIRONMENT to switch between sandbox and production:

# Sandbox (default)
export STRADDLE_ENVIRONMENT="sandbox"
export STRADDLE_API_KEY="your-sandbox-api-key"

# Production -- restrict to read-only so the agent cannot mutate resources
export STRADDLE_ENVIRONMENT="production"
export STRADDLE_API_KEY="your-production-api-key"

API keys are JWT bearer tokens. The environment is determined by the base URL, not the key format.

For advanced configuration (transport, tool filtering, client presets, production safety), see the MCP server reference.

What you get

Skills

Skills activate automatically based on what you're doing. No slash command needed.

| Skill | When it activates | What it does | |-------|-------------------|--------------| | Setup | First-time setup, connecting MCP servers, configuring environments | Walks through API key setup, MCP connection, and environment selection | | Plan | Planning a new Straddle integration from scratch | Runs a guided conversation (5-8 questions) that produces a complete integration plan tailored to your use case | | Integrate | Building payment flows, working with Straddle APIs and SDKs | Guides integration decisions: customers, paykeys, charges, payouts, Bridge, Embed, webhooks, ACH returns |

Commands

| Command | What it does | |---------|--------------| | /straddle-setup | First-time setup wizard: MCP servers, CLI, environment, integration type | | /explain-status | Explain any Straddle status, transition, or error. Example: /explain-status charge failed | | /sandbox-test | Guided sandbox testing scenarios. Example: /sandbox-test payment-lifecycle |

Available sandbox test scenarios: payment-lifecycle, payout-flow, failures, ach-returns, funding, bridge, embed-onboarding, webhooks.

MCP Tools

| Tool | Server | Description | |------|--------|-------------| | Code execution | API MCP | Run code against Straddle's sandbox | | SDK docs search | API MCP | Search SDK and API reference documentation | | Product docs search | product-docs skill | Search product guides and tutorials |

SDKs

| SDK | Package | Repo | |-----|---------|------| | TypeScript | @straddlecom/straddle | straddleio/straddle-node | | Python | straddle | straddleio/straddle-python | | Go | straddle-go | straddleio/straddle-go | | Ruby | straddle | straddleio/straddle-ruby | | C# | Straddle | straddleio/straddle-csharp |

SDK reference docs: sdk.straddle.com

Supported Editors

| Editor | Status | Features | |--------|--------|----------| | Claude Code | Available | Plugin with skills, commands, and MCP | | Cowork | Available | Same plugin as Claude Code | | Codex | Available | Plugin with skills and MCP | | Cursor | Available | Skills and MCP |

Additional editor support is in development.

Community

Join our developer community for help, support, and feedback.


Learn more

• Straddle documentation
• API reference
• Sandbox testing guide
• Security policy
• Contributing

License

MIT -- see LICENSE.