Orca MCP Server

The Orca MCP server exposes Orca as Model Context Protocol tools. AI agents like Claude Desktop, Cursor, Claude Code, and any MCP client can check customer entitlements, manage subscriptions, and connect payment stores using natural language.

Capabilities

The server provides two groups of tools, each authenticated with a different API key sent in the api-key header. Set whichever keys you need.

Backend tools

These tools require a private key (Orca_API_KEY).

Tool	Description
Orca_check_customer_entitlements	Check whether a customer has active premium access on any store. This is the single source of truth for entitlement status.
Orca_list_customers	List customers with cursor-based pagination.
Orca_cancel_stripe_subscription	Cancel a customer’s Stripe subscription.
Orca_cancel_gocardless_subscription	Cancel a customer’s GoCardless subscription.

Management tools

These tools require a management key (Orca_MANAGEMENT_API_KEY).

Tool	Description
Orca_list_apps	List all apps in your organization.
Orca_create_app	Create a new app.
Orca_list_entitlements	List entitlements for an app.
Orca_create_entitlement	Create a new entitlement.
Orca_list_products	List products linked to an entitlement.
Orca_get_store_config	View which stores are connected to an app. Secrets are not returned.
Orca_store_connection_guide	Get step-by-step instructions for connecting a store, including dashboard location, webhook URLs, and which fields are secret.

Note

Store secrets are entered only in the Orca dashboard. The MCP server has no tool that accepts store credentials, and the API rejects store-config writes from API keys. The server guides you through the process, but you paste secrets directly in the dashboard UI.

Get your API keys

In the dashboard, navigate to Orca Dashboard > API Keys > Create New Key and choose the key type you need:

• Secret (private): For backend tools. Keep this server-side only.
• Management: For management and store-config tools. This key acts on your behalf with your org role. Keep it server-side.

Publishable and public keys are intended for client SDKs and are rejected by the MCP server.

Configure your client

Add the following configuration to your MCP client. This works with Claude Desktop, Cursor, Claude Code, and other stdio-based clients.

{
  "mcpServers": {
    "Orca": {
      "command": "npx",
      "args": ["-y", "@Orca/mcp-server"],
      "env": {
        "Orca_API_KEY": "your_private_key",
        "Orca_MANAGEMENT_API_KEY": "your_management_key",
        "Orca_BASE_URL": "https://api.Orca.dev"
      }
    }
  }
}

You do not need to set both keys. Set only the keys for the tools you plan to use. Each tool returns a clear error if its required key is missing.

Example prompts

Here are some things you can ask your AI agent once the MCP server is configured:

• “Does [email protected] still have premium access?”
• “List my apps, then show which stores my Acme app has connected.”
• “How do I connect Stripe to my Acme app?” The agent returns a setup guide. You enter the secrets in the dashboard. See the store onboarding skill for details.
• “Cancel [email protected]’s Stripe subscription for the pro entitlement.”

Security

• Treat the management key like a password. Store it in a secrets vault or environment variable. Never commit it to client code.
• Store-config tools forward credentials (Stripe keys, GoCardless tokens, service-account JSON) to Orca and never echo them back. Orca validates every credential live at connect time.
• You can revoke keys at any time from the dashboard.

Self-hosted

Point Orca_BASE_URL at your own instance (for example, http://localhost:8080). Set TRANSPORT=http to run a remote streamable-HTTP server instead of stdio.

For source code and full documentation, see the Orca-mcp-server package.