MCP server

The CashSDK Model Context Protocol server is hosted, so there is nothing to install. It's a thin, stateless proxy over the CashSDK REST API: every tool maps to an API call made with the token you send, so an agent can create apps, manage catalog, build paywalls, wire webhooks and read revenue without ever holding your dashboard session.

Choose how to authenticate#

Get an MCP token#

Dashboard → Settings → MCP → Create token. Copy it immediately; the full value is shown once and stored only as a hash.

• Workspace-wide by default, so an agent can call list_apps and create_app before any app exists.
• Narrow it to one app if you'd rather it could only touch that one. The restriction is real. A narrowed token gets 403 on a sibling app in the same workspace.
• Choose Read only for analytics, diagnostics, and support agents that should inspect state without changing it. Read-only tokens receive 403 for every mutating API call, including calls made through MCP tools.
• It does not expire. Revoke it in the dashboard when you're done, and any agent using it stops on its next call.

Or use the setup token#

Quickstart’s Generate Prompt defaults to browser sign-in and contains no token. Choose Generate token fallback only when needed: it issues a csk_st_… token restricted to one app and provisioning actions. It expires in 24 hours; issuing another revokes the last. Other integration-prompt entry points may still issue this token directly. Use OAuth or an csk_mcp_… token for an ongoing connection.

Browser approval is not proof of tool access. After signing in and approving the intended workspace/app, call get_setup_checklist for that app. OAuth can permit broader operations than a setup token; review permissions and restrict access to the app. The user, not the agent, must approve consent.

Client configuration#

Header-based clients need the URL and an Authorization header:

{
  "mcpServers": {
    "cashsdk": {
      "url": "https://mcp.cashsdk.com/mcp",
      "headers": { "Authorization": "Bearer csk_mcp_..." }
    }
  }
}

The exact file differs per client. See Claude Code, Cursor and Codex. For Claude on the web or Claude Desktop, add a custom connector and paste https://mcp.cashsdk.com/mcp; you'll be asked to sign in and pick a workspace.

Verify it's connected#

curl -s https://mcp.cashsdk.com/mcp \
  -H "Authorization: Bearer csk_mcp_..." \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | head -c 400

A list of tools comes back. Without a valid credential you get 401 with a WWW-Authenticate header carrying resource_metadata. That pointer is what tells an OAuth client where to authenticate, and what tells a token client its token has been revoked or has expired.

If the connection works but newer platform tools are missing, refresh the client's MCP tool list or disconnect and reconnect CashSDK, then start a new agent conversation. Some clients keep the tool schema loaded when the conversation began. Reconnecting an existing client updates that catalog; reinstalling an SDK does not. Confirm that get_integration_snippets is available before setting up web, direct macOS, Chrome extensions or standalone Stripe. If it is still missing, check the configured server URL and report the missing tool with your client version.

What an agent can't do#

Some of the API is refused for every MCP token, at every role, regardless of what the person who created it can do in the dashboard. An agent reads store listings, webhook payloads and READMEs, any of which can try to steer it, so the boundary is drawn in code rather than left to a prompt:

Within what's left, a token can never exceed the member who created it, and every call passes the same AccessService and role checks a dashboard session does. The token's own read/write permission is enforced in addition to those checks.

An app-scoped token cannot call workspace-wide routes, including listing or creating apps. Use a workspace token when those operations are intended. Setup tokens can only be issued by an owner/admin and act as that issuer while their membership remains active and privileged. They cannot create/rotate SDK keys or register webhook endpoints; add those in the dashboard.

Every change an agent makes lands in your workspace audit log with actorType: "agent" (or agent_setup for the onboarding setup token), alongside the member whose credential it used, so "was that change mine or my agent's?" has an answer. Reads are not logged, on MCP or anywhere else.

Rate limits#

Set well above what a working agent does (a busy setup session bursts dozens of tool calls a minute) so you should never see one. They exist because these endpoints are unauthenticated by construction and would otherwise be free database load.

Every platform, including Stripe only#

Call list_supported_platforms for the current choices and distribution status: ios, macos (Mac App Store), android, web, macos-direct, chrome-extension and stripe. Create apps with platforms; a bundle ID is only required when a native store is selected. update_app_settings accepts the full platform list when adding a channel.

Commerce configuration and identity writes require owner/admin OAuth or a write-enabled MCP token. Setup tokens may read commerce configuration and snippets; they cannot change origins, install provider credentials, import Stripe prices, sync provider history or reassign customer access. Use the dashboard for those steps when working with a setup token.

Read the platform guides for package availability and verification. A sandbox check does not certify production: follow Go live with Stripe before taking real payments.

Tools#

Tools are grouped by what they touch. Each maps directly onto a REST endpoint, so results are the same JSON your backend would receive.

OAuth details#

For anyone implementing against it directly:

PKCE is required and only S256 is accepted. Access tokens live one hour; refresh tokens live 30 days and rotate on every use. Redirect URIs are matched exactly against what the client registered, with a loopback exception for native clients (RFC 8252 §7.3).

Per-client setup#

Next steps#