Developers

MCP for AI agents

Connect AI assistants and IDEs straight to your Soca account over the Model Context Protocol: the /api/mcp remote server, OAuth 2.1 or API-key auth, and the tools it exposes for invoices, plans, usage, credits, and entitlements.

The Model Context Protocol (MCP) is an open standard that lets AI clients, including Claude, IDEs, and agent frameworks, call external tools directly. Soca ships a remote MCP server that exposes the developer API as tools, so an AI can create invoices and plans and read your payment data on your behalf, with your approval.

Connecting

Add a remote MCP connector pointing at:

https://soca.to/api/mcp

The path is always /api/mcp on whatever host serves your Soca deployment. If you self-host, use your own origin. The server speaks Streamable HTTP: JSON-RPC 2.0 over POST /api/mcp, with single responses returned as plain JSON.

Authentication

There are two options. Both end up scoped to exactly one merchant and one mode, the same isolation as the REST API:

OAuth 2.1 (recommended for AI clients). The client discovers the authorization server at /.well-known/oauth-authorization-server, registers itself (dynamic client registration is supported), and walks you through a consent screen; PKCE with S256 is required. An unauthenticated request to /api/mcp returns 401 with a WWW-Authenticate header pointing at the resource metadata (/.well-known/oauth-protected-resource), which is how OAuth-capable clients find the flow on their own.
Static API key. Send Authorization: Bearer sk_live_... (or sk_test_...): the same secret key as the REST API. Simpler for server-side agents you run yourself.

The tools

Tool	What it does
`create_invoice`	Create a one-time USDC invoice (`amount`, `description`, …) and get a hosted `checkout_url` to send the customer.
`create_plan`	Create a subscription plan and get a hosted `checkout_url`. Fixed, or `usage_type: "metered"` to auto-charge usage each period up to a cap.
`create_meter`	Create a meter (`key`, `display_name`, `aggregation`) — the named thing usage is recorded against.
`create_feature`	Create a feature to gate with entitlements (`boolean` or `metered`).
`create_meter_event`	Record one usage event against a meter (`event_name`, `customer_id`, `value`, `idempotency_key`).
`grant_credits` / `debit_credits`	Top up or draw down a customer's prepaid balance. Idempotent.
`get_credit_balance`	Read a customer's balance plus lifetime granted/consumed.
`grant_entitlement` / `check_entitlement`	Grant a feature to a customer, and ask yes/no whether they may use it now.
`list_payments`	List recent payments, newest first (`limit`, `before`).
`list_subscriptions`	List subscriptions, newest first (`limit`, `before`).
`list_invoices`	List invoices, newest first (`limit`, `before`).
`list_events`	List the event feed, newest first (`limit`, `before`).
`list_meters`	List your meters, newest first (`limit`, `before`).

Every tool runs through the exact same validation and creation code as its REST endpoint — one implementation serves both surfaces, so they cannot drift. Amounts are USDC base units here too. For a usage-based plan, create_meter first, then reference its id as create_plan’s meter.

What it looks like in practice

Once connected, you work in plain language. Ask your AI client:

"Invoice Acme $250 for the March retainer and give me the payment link.": the agent calls create_invoice and hands back the checkout_url.
"Set up a $9/month Pro plan.": create_plan, returning the subscription checkout link.
"What did we collect this week?": list_payments, summarized by the model.
"Did invoice INV-1041 get paid?": list_invoices / list_events.

Properties worth knowing

Stateless. No sessions or server-initiated SSE stream. Each request stands alone (GET /api/mcp returns 405). Any number of clients can connect concurrently.
Mode-scoped. A test credential can only ever touch test data. Connect with an sk_test_ key first to try things safely.
Rate limited. 120 requests per minute, like the REST read endpoints.
Money-safe by design. The tools create payable objects and read state; they cannot move funds, change your settlement wallet, or issue refunds.

AI tools that just want documentation rather than a live connection can read /llms.txt and /llms-full.txt: machine-readable versions of this documentation.

Was this page helpful?

A quick signal helps us improve the right pages.

How Telegram and Discord access works

Errors and testing