> ## Documentation Index
> Fetch the complete documentation index at: https://docs.withorb.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Orb MCP server

> Connect Claude, Cursor, Codex and other AI agents to your Orb account.

> [!NOTE]
>
> We're actively improving the Orb MCP server based on how teams use it, and adding tools and capabilities regularly. If there's a workflow you'd like it to support or something that doesn't work the way you expect, let your Orb contact know.

The Orb MCP server is a hosted [Model Context Protocol](https://modelcontextprotocol.io) server. It lets AI agents such as Claude, Cursor and Codex work directly with your Orb account. It exposes 100+ Orb API operations as tools, covering customers, subscriptions, plans and prices, billable metrics, invoices, credits, alerts, licenses, event search and price evaluation.

You can ask an agent to look into a customer's bill, check why usage isn't showing up, model a price change, or make a subscription change, and it calls the Orb API for you.

| | |
| - | - |
| **URL** | `https://mcp.withorb.com/mcp` |
| **Transport** | Streamable HTTP |
| **Authentication** | `Authorization: Bearer <your-orb-api-key>` |

The server acts with the permissions of the Orb API key you connect it with. With full access, an agent can do everything the tools cover, from looking up invoices to creating subscriptions and granting credits. Scoped API keys let you decide exactly how much of that to allow.

## Set up

### 1. Create an API key

In the Orb web app, go to **Developers → API keys** and create a key. Give it only the scopes the agent needs for the work you have in mind.

Each scope covers one area of Orb, such as customers and credits, subscriptions, invoices, plans or prices, and can be set to **none**, **read** or **write**. For example:

* **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.

A tool call that's outside the key's scopes fails with a permissions error, and the agent tells you which access it was missing. To try things out without touching live billing data, create the key in **test mode**.

### 2. Add the server to your client

> [!WARNING]
>
> Never commit your Orb API key to version control. Store it in an environment variable and reference that from your MCP configuration, or keep the configuration in a file outside your repository.

Set the key as an environment variable in your shell profile, a secrets manager or your team's usual secret-injection tool:

```bash theme={null}
export ORB_API_KEY="<your-orb-api-key>"
```

**Claude Code**

```bash theme={null}
claude mcp add --transport http orb https://mcp.withorb.com/mcp \
  --header "Authorization: Bearer $ORB_API_KEY"
```

By default, this saves the server in Claude Code's `local` scope, which lives in `~/.claude.json` in your home directory rather than in your project, so the key stays out of your repository.

To share the server with your team through a checked-in `.mcp.json`, reference the variable instead of the key. Claude Code expands `${ORB_API_KEY}` from each person's environment when it loads the file:

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

**Cursor**

Add the server to `~/.cursor/mcp.json` to use it in every project, or to `.cursor/mcp.json` to use it in one project. In either file, reference the environment variable with `${env:ORB_API_KEY}` instead of pasting the key, so the file is safe to commit:

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

**Codex**

Add the server to `~/.codex/config.toml` to use it in every project, or to `.codex/config.toml` in a trusted project. Set `bearer_token_env_var` to the name of the environment variable, not the key itself. Codex reads the key from that variable and sends it in the `Authorization` header, so the file never contains the key:

```toml theme={null}
[mcp_servers.orb]
url = "https://mcp.withorb.com/mcp"
bearer_token_env_var = "ORB_API_KEY"
```

**Other clients**

Most clients accept an `mcpServers` entry with a `url` and `headers`. Check your client's documentation for how it references environment variables or secrets, and use that instead of the literal key.

If your client only accepts the key directly in its configuration file, keep that file outside your repository, for example in your home directory, or add it to `.gitignore` before you put the key in it.

### 3. Test the connection

Ask the agent to **"ping Orb"**. It calls the `ping` tool, which confirms the server is reachable and your key is valid.

If the key is wrong or missing, the first tool call fails with a `401` error. Check that `ORB_API_KEY` is set in the environment your client starts from, and that the header is exactly `Authorization: Bearer <key>` with no extra quotes or spaces. Apps launched from the dock or Start menu may not see variables set in your shell profile, so restart the client from a terminal where the variable is set.

## Authentication

The server holds no credentials of its own. It forwards the API key you configure to the Orb API, which decides which account the key belongs to and what it's allowed to do. A tool call can never reach further than the key you gave it.

> [!NOTE]
>
> **OAuth is coming soon.** Today the server only accepts an API key in the `Authorization` header. Clients that try to sign in with OAuth won't be able to connect yet, so configure the header explicitly.

## What you can do

You don't need to know tool names to use the server. Describe what you want in plain language, and the agent picks the tools, chains calls together, and summarizes the results. The examples below show the kinds of tasks the server is good at and the tools the agent typically uses for each.

### Investigate a customer's bill

Support and finance teams often need to answer "why is this invoice what it is?" The agent can pull the customer, their subscription, the invoice and the usage behind it, and explain the difference in one answer.

> *"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."*

The agent typically uses `fetch_customer_external_id`, `list_invoices`, `fetch_invoice`, `fetch_upcoming_invoice`, `fetch_subscription_usage` and `fetch_subscription_costs`.

### Debug usage and events

When a customer says their usage is wrong, the agent can check your event volume for gaps, look up specific events, compare usage against the billable metric definition, and see whether a backfill is in progress.

> *"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?"*

The agent typically uses `search_events`, `get_event_volume`, `fetch_metric`, `list_metrics`, `fetch_subscription_usage`, `list_backfills` and `fetch_backfill`.

> [!NOTE]
>
> Event search looks up events by their IDs (the idempotency keys they were ingested with) within a window of up to 30 days. It doesn't search by customer or event name. The MCP server also doesn't ingest, amend or deprecate events. Keep sending events through the [event ingestion API](/events-and-metrics/event-ingestion.md).

### Model pricing changes

Before you change a price, the agent can evaluate it against real usage and compare it to what customers pay today.

> *"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?"*

The agent typically uses `list_plans`, `fetch_plan`, `evaluate_price`, `evaluate_multiple_prices`, `evaluate_preview_events` and `fetch_customer_costs`.

Price evaluation runs against one customer's events at a time, for time ranges that start no more than 100 days ago, and can test existing prices or new ones defined on the fly. To compare several customers, the agent runs one evaluation per customer.

### Build and maintain your catalog

The agent can set up new metrics, items, prices and plans, and roll out new plan versions.

> *"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?"*

The agent typically uses `create_metric`, `create_item`, `create_price`, `create_plan`, `create_plan_version`, `set_default_version`, `list_prices`, `list_migrations` and `fetch_migration`.

### Manage subscriptions

The agent can start, change and cancel subscriptions. It handles the multi-step parts, such as looking up the right plan and IDs, for you.

> *"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."*

The agent typically uses `create_subscription`, `fetch_subscription`, `schedule_plan_change`, `update_fixed_fee_quantity`, `add_edit_price_intervals`, `update_trial`, `cancel_subscription`, `unschedule_cancellation`, `redeem_coupon` and `fetch_subscription_schedule`. For pending changes, it can use `list_subscription_changes`, `apply_subscription_change` and `cancel_subscription_change`.

### Manage prepaid credits

For prepaid and commitment-based pricing, the agent can check balances, explain ledger activity and grant or adjust 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."*

The agent typically uses `fetch_customer_credits`, `fetch_customer_credits_ledger`, `create_ledger_entry`, `list_top_ups`, `create_top_up`, `delete_top_up`, `fetch_credit_block` and `list_credit_block_invoices`.

### Work with invoices and collections

The agent can find invoices by status, make one-off adjustments and move invoices through their lifecycle.

> *"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."*

The agent typically uses `list_invoices_summary`, `list_invoices`, `fetch_invoice`, `create_invoice`, `create_invoice_line_item`, `update_invoice`, `issue_invoice`, `void_invoice`, `mark_invoice_as_paid`, `pay_invoice` and `create_credit_note`.

### Set up usage alerts

The agent can create and manage alerts so you or your customers find out about usage or credit thresholds before the invoice does.

> *"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?"*

The agent typically uses `create_customer_alert`, `create_subscription_alert`, `create_plan_alert`, `list_alerts`, `update_alert`, `enable_alert` and `disable_alert`.

### Manage licenses and seats

For seat-based pricing, the agent can add and remove licenses and report license usage.

> *"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?"*

The agent typically uses `list_license_types`, `create_license`, `deactivate_license`, `list_licenses`, `get_license_usage_by_id` and `get_license_usage_by_type`.

### Combine Orb with your other tools

The server is most useful alongside the other tools your agent already has. For example:

* **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

Each tool maps to one Orb API endpoint, and its name is the endpoint's operation ID. Tool inputs mirror the API's parameters, so the [API reference](/api-reference/introduction) documents each one in detail.

> **Customers**
>
> `fetch_customer`, `fetch_customer_external_id`, `list_customers`, `create_customer`, `update_customer`, `fetch_customer_costs`, `list_balance_transactions`, `create_customer_balance_transaction`

> **Credits**
>
> `fetch_customer_credits`, `fetch_customer_credits_ledger`, `create_ledger_entry`, `list_top_ups`, `create_top_up`, `delete_top_up`, `fetch_credit_block`, `list_credit_block_invoices`

> **Subscriptions**
>
> `fetch_subscription`, `list_subscriptions`, `create_subscription`, `update_subscription`, `cancel_subscription`, `unschedule_cancellation`, `fetch_subscription_schedule`, `schedule_plan_change`, `unschedule_plan_change`, `update_trial`, `fetch_subscription_usage`, `fetch_subscription_costs`, `update_fixed_fee_quantity`, `unschedule_fixed_fee_quantity`, `add_edit_price_intervals`, `trigger_phase`, `redeem_coupon`

> **Subscription changes**
>
> `fetch_subscription_change`, `list_subscription_changes`, `apply_subscription_change`, `cancel_subscription_change`

> **Plans and migrations**
>
> `list_plans`, `fetch_plan`, `fetch_plan_external_id`, `fetch_plan_version`, `create_plan`, `update_plan`, `create_plan_version`, `set_default_version`, `list_migrations`, `fetch_migration`, `cancel_migration`

> **Prices and price evaluation**
>
> `list_prices`, `fetch_price`, `fetch_price_external_id`, `create_price`, `update_price`, `evaluate_price`, `evaluate_multiple_prices`, `evaluate_preview_events`

> **Dimensional price groups**
>
> `list_dimensional_price_groups`, `fetch_dimensional_price_group`, `fetch_dimensional_price_group_external_id`, `create_dimensional_price_group`, `update_dimensional_price_group`

> **Items**
>
> `list_items`, `fetch_item`, `create_item`, `update_item`, `archive_item`

> **Billable metrics**
>
> `list_metrics`, `fetch_metric`, `create_metric`, `update_metric`

> **Events**
>
> `search_events`, `get_event_volume`, `list_backfills`, `fetch_backfill`

> **Invoices**
>
> `list_invoices`, `list_invoices_summary`, `fetch_invoice`, `fetch_upcoming_invoice`, `create_invoice`, `update_invoice`, `issue_invoice`, `void_invoice`, `mark_invoice_as_paid`, `pay_invoice`, `create_invoice_line_item`, `delete_invoice_line_item`

> **Credit notes**
>
> `list_credit_notes`, `fetch_credit_note`, `create_credit_note`

> **Coupons**
>
> `list_coupons`, `fetch_coupon`, `create_coupon`, `archive_coupon`, `list_coupon_subscriptions`

> **Alerts**
>
> `list_alerts`, `fetch_alert`, `create_customer_alert`, `create_subscription_alert`, `create_plan_alert`, `update_alert`, `enable_alert`, `disable_alert`, `delete_alert`

> **Licenses**
>
> `list_license_types`, `fetch_license_type`, `create_license_type`, `list_licenses`, `fetch_license`, `fetch_license_external_id`, `create_license`, `deactivate_license`, `get_license_usage_by_id`, `get_license_usage_by_type`

> **Availability**
>
> `ping`

## 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](/api-reference/idempotency). 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](/api-reference/rate-limits.md).

## What's next

We're expanding the server based on feedback. Today:

* 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.