Orca MCP Server

The Orca MCP server exposes Orca as Model Context Protocol tools. Claude Desktop, Claude Code, Cursor and any other MCP client can check customer access, run billing operations, create products across every store, and wire up webhooks, using plain language.

There are two ways to connect. Use the hosted server unless you have a reason not to.

Option 1: Hosted server (recommended)

Nothing to install. You sign in to Orca in your browser and pick what the agent is allowed to do.

Claude Desktop / claude.ai: add a custom connector pointing at:

https://mcp.orca.maxint.com

Claude Code:

$ claude mcp add --transport http orca https://mcp.orca.maxint.com

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "orca": {
      "url": "https://mcp.orca.maxint.com"
    }
  }
}

The first time the agent uses a tool, a browser window opens. Sign in to Orca, choose which organization to give access to, tick the permissions you want to allow, and you’re done. No API keys anywhere.

Permissions

The consent screen asks for up to three things. Only approve what you need.

• Read your Orca data (orca:read) - check whether customers have paid access, list customers, entitlements and products, see which stores are connected, preview product plans.
• Create apps, products and webhooks (orca:write) - create apps and entitlements, provision products across your stores, register webhook endpoints. Can’t cancel anything.
• Cancel customer subscriptions (orca:destructive) - end a customer’s Stripe or GoCardless subscription. Affects real paying customers.

Cancellation sits behind its own permission on purpose, so you can hand an agent day to day access without giving it the ability to cut off a paying customer. If you skip a permission and later need it, the agent tells you which one is missing and you can re-authorize.

You can revoke access at any time from the dashboard.

Option 2: Run it locally

Use this if you’re working against a self-hosted Orca, you’re offline, or you’d rather use API keys than sign in.

Requirements:

• Node.js 20 or newer

Sign in

$ npx -y @orca/mcp-server login

This opens your browser once, you pick an organization and approve the permissions, and a token is stored in ~/.orca/credentials.json and refreshed automatically. It covers every tool on the dashboard plane: apps, entitlements, products, store status and webhooks.

npx @orca/mcp-server status shows what you’re signed in as, logout clears it.

Optional: an API key for the customer tools

The three customer tools (access check, customer list, cancellation) run on the tenant-server plane, which takes a private app key rather than your sign-in. Get one from API Keys if you need them.

Public keys are meant for client SDKs and every tool here rejects them.

Configure your client

{
  "mcpServers": {
    "orca": {
      "command": "npx",
      "args": ["-y", "@orca/mcp-server"],
      "env": {
        "ORCA_API_KEY": "your_private_key",
        "ORCA_ORG_ID": "your_org_uuid",
        "ORCA_APP_ID": "your_app_uuid"
      }
    }
  }
}

ORCA_API_KEY is optional - leave it out if you only need the dashboard tools.

ORCA_ORG_ID and ORCA_APP_ID are optional but worth setting. Without them the agent has to look up and carry UUIDs around on every call. Tools also accept an org or app name in place of a UUID.

What the agent can do

Customer and billing operations (private key):

Tool	Does
orca_customer_access_check	Whether a customer has active paid access on any store. The single source of truth.
orca_customers_list	List customers with their entitlements, cursor paginated.
orca_subscription_cancel	Cancel a Stripe or GoCardless subscription. Destructive.

Apps, products and stores (management key):

Tool	Does
orca_orgs_list	Your organizations.
orca_apps_list	Apps in an organization, with enabled stores.
orca_app_create	Create an app.
orca_entitlements_list	Access tiers and their UUIDs.
orca_entitlement_create	Create an access tier.
orca_entitlement_products_list	Store products linked to a tier.
orca_product_plan	Build a reviewable cross-store product plan. Creates nothing.
orca_product_provision	Execute a reviewed plan across Play Store, App Store, Stripe and GoCardless at once.
orca_store_products_list	Existing Play products and App Store subscription groups, to reuse instead of duplicating.
orca_store_status	All four stores in one call: connected or not, plus each notification URL.
orca_webhook_endpoint_setup	Register an outbound webhook and get the Ed25519 public key and verification recipe.
orca_store_connection_guide	What each store needs, which values are secret, and where they go.

Creating a product is the one worth calling out. Ask for it in plain language and the agent builds a plan with orca_product_plan, shows you the real prices per store (Apple only allows its own price points, Google converts per region), and only creates anything after you say yes.

Things you can ask

• “Does alice@example.com still have premium access?”
• “Which of my stores are actually connected?”
• “Create a Pro Monthly subscription at $9.99 with a 7 day free trial on Stripe and Play Store.”
• “How do I connect Stripe to my Acme app?”
• “Set up a webhook to https://api.example.com/orca and show me how to verify the signature.”
• “Cancel bob@example.com’s Stripe subscription for the pro entitlement.”

Security

Store credentials, meaning Stripe keys, GoCardless tokens, Play service account JSON and Apple .p8 keys, are never passed through the MCP server or an agent. No tool accepts them and the API rejects store config writes from API keys. You paste them in the dashboard, which validates them live.

orca_app_create doesn’t return the API keys Orca mints with a new app, even though the API includes them. Read those from the dashboard instead of letting them sit in an agent transcript.

The only destructive tool is orca_subscription_cancel, and it’s marked as such so your client can prompt before it runs.

Pair it with the skills

The MCP server gives the agent the actions. The Orca Skills give it the knowledge: the data model, the right order of steps, and the traps. Install both and the agent can take you from an empty dashboard to a working integration. Each works without the other.

Self hosting

Point ORCA_BASE_URL at your own instance, for example http://localhost:8080. To run the server itself as a remote endpoint rather than locally, see the deployment guide in the orca-mcp-server repository.