Orb MCP server

​

Set up

​

1. Create an API key

• Support and finance lookups: read access to customers, subscriptions and invoices.
• Usage debugging and pricing analysis: read access to customers, subscriptions, events, metrics, plans and prices. Event search and price evaluation only need read access.
• Catalog work: write access to metrics, items, prices and plans, and no access to customers or invoices.
• Account operations: write access to customers (which includes credits), subscriptions, invoices and credit notes.

​

2. Add the server to your client

export ORB_API_KEY="<your-orb-api-key>"

claude mcp add --transport http orb https://mcp.withorb.com/mcp \
  --header "Authorization: Bearer $ORB_API_KEY"

{
  "mcpServers": {
    "orb": {
      "type": "http",
      "url": "https://mcp.withorb.com/mcp",
      "headers": {
        "Authorization": "Bearer ${ORB_API_KEY}"
      }
    }
  }
}

{
  "mcpServers": {
    "orb": {
      "url": "https://mcp.withorb.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:ORB_API_KEY}"
      }
    }
  }
}

[mcp_servers.orb]
url = "https://mcp.withorb.com/mcp"
bearer_token_env_var = "ORB_API_KEY"

​

3. Test the connection

​

Authentication

​

What you can do

​

Investigate a customer’s bill

“Acme’s October invoice is 40% higher than September. Find out why.”

“What will customer cus_123 be billed at the end of this period, and which line items drive most of it?”

“Show me every invoice for external customer ID acme-corp this year with its status and amount due.”

​

Debug usage and events

“Acme says their usage for October 3 looks low. Check our event volume around that day for gaps, and compare it with the usage on their subscription.”

“Look up events evt_123 and evt_456. Which customer were they recorded against, and with which properties?”

“How is the compute_hours metric defined, and which plans use it?”

“Are there any backfills that haven’t been reflected yet?”

​

Model pricing changes

“If we moved Acme from the Growth plan to the new Scale plan, what would they have paid last month?”

“Evaluate a tiered price of $0.10 per unit for the first 10,000 API calls and $0.07 after that against Acme’s usage last month, and compare it with what they actually paid.”

“Given these sample events, what would each price on the Enterprise plan charge?”

​

Build and maintain your catalog

“Create a billable metric that sums the tokens property on llm_request events, then create a plan called ‘AI Starter’ with a $20 monthly fee and $0.002 per 1,000 tokens.”

“Add a new version of the Pro plan that raises the platform fee to $500, but don’t make it the default yet.”

“List every plan that still uses the legacy storage_gb price and show their active subscription counts.”

“How is the migration of Pro plan subscribers to version 3 going?”

​

Manage subscriptions

“Upgrade customer cus_123 to the Enterprise plan at the start of their next billing period.”

“Bump Acme’s seat count from 50 to 75, effective today.”

“Extend the trial for sub_456 by two weeks.”

“Cancel Globex’s subscription at the end of the term, and tell me what their final invoice will look like.”

“Apply coupon LAUNCH20 to Initech’s subscription.”

​

Manage prepaid credits

“What’s Acme’s remaining credit balance, and when do their current blocks expire?”

“Walk me through every ledger entry for cus_123 this month.”

“Grant Acme 10,000 promotional credits that expire on December 31.”

“Set up an automatic top-up for Globex: when their balance drops below 1,000 credits, buy 5,000 more.”

​

Work with invoices and collections

“List all past-due invoices over $10,000, sorted by how long they’ve been overdue.”

“Add a $250 onboarding fee to Acme’s draft invoice, then issue it.”

“Mark invoice inv_789 as paid, since they paid by wire on October 10.”

“Issue a credit note for $100 on Initech’s last invoice for the outage last week.”

​

Set up usage alerts

“Alert me when any subscription on the Growth plan crosses $5,000 in usage this period.”

“Create an alert for Acme when their credit balance drops below 500.”

“Which of Acme’s alerts are currently disabled?”

​

Manage licenses and seats

“Add a license for jane@acme.com on Acme’s subscription.”

“How many active editor licenses does Acme have, and how much have they used this billing period?”

​

Combine Orb with your other tools

• With your codebase: “Our app sends api_request events from usage.ts. Check that the property names match what the api_calls metric in Orb expects.”
• With your CRM or support tool: “This support ticket says the customer was double-billed. Find the invoices in Orb and draft a reply.”
• With a spreadsheet or data tool: “Pull every active subscription on legacy plans and export it as a CSV I can share with the sales team.”

​

Tool reference

​

Good to know

• Review changes before the agent makes them. Most clients ask you to approve each tool call. Keep that on for tools that write data, and ask the agent to describe what it’s about to do before a bulk change.
• Idempotency. Tools that create or change data with a POST request accept an optional idempotency_key argument, sent as the Idempotency-Key header. If the agent retries a call after a timeout with the same key, Orb doesn’t apply the change twice.
• Response size. A single tool result is capped at about 1 MB. If a list call hits the limit, the agent gets an error asking it to retry with a smaller limit or a narrower filter, and usually does so on its own.
• Filter argument names. Query parameters with brackets in the API are renamed for tools. For example, created_at[gte] becomes created_at_gte.
• Errors. When the Orb API returns an error, the tool returns the status code and error body to the agent, so it can see what went wrong and try again.
• Rate limits. Tool calls count against your account’s normal API rate limits.

​

What’s next

• OAuth is coming soon. Until then, authenticate with an API key.
• Event ingestion, amendment and deprecation aren’t available as tools.
• The tools cover most of the Orb API, and we’re adding more. Tell us which ones matter most to you.