# Agents & MCP

Source: https://docs.orbytelabs.com/agents

Integrate Credit with a coding agent or connect an assistant to inspect customers, balances, and usage.

Use a coding agent to add Credit to your application, or connect the
[MCP server](#mcp-server) to investigate existing customer data.

## Set up with an agent [#set-up-with-an-agent]

Paste this into your coding agent from your application's directory:

```text title="Copy this prompt"
Set up Orbyte Labs credit billing in this project by following
https://docs.orbytelabs.com/skills/orbyte-onboard/SKILL.md.
Implement and verify the development integration, preserving existing billing rules.
```

Your agent inspects the codebase, installs the tools, creates `orbyte.config.ts`,
and deploys its catalog to a development environment before connecting `check`
and `track` to billable operations. It uses the migration workflow if billing
already exists. You confirm device login and supply any account or pricing
decisions the code does not establish. Live billing cutover is separate.

The tools require Node.js 24+ and `orbytelabs` 0.1.1+. JavaScript and TypeScript
apps use the SDK; other languages can use the HTTP API.

### Install the skills directly [#install-the-skills-directly]

From your application's directory:

```sh
npm install orbytelabs@latest
npx --yes skills add ./node_modules/orbytelabs
```

The local path points to the public npm package, which bundles all four skills.
No repository access is required. Choose the skills and your coding agent in the
installer. For all four skills without prompts, add `--skill '*' --agent codex --yes`,
using your agent's ID in place of `codex`. Rerun after updating the SDK to refresh them.

| Skill                                                 | Purpose                                                                                |
| ----------------------------------------------------- | -------------------------------------------------------------------------------------- |
| [orbyte-onboard](/skills/orbyte-onboard/SKILL.md)     | Inspect the project and choose the workflow.                                           |
| [orbyte-setup](/skills/orbyte-setup/SKILL.md)         | Create and deploy `orbyte.config.ts`, link an environment, and configure a server key. |
| [orbyte-integrate](/skills/orbyte-integrate/SKILL.md) | Connect and verify real usage tracking.                                                |
| [orbyte-migrate](/skills/orbyte-migrate/SKILL.md)     | Preserve existing billing rules and prepare cutover.                                   |

You can also give your agent a skill URL directly. Each returns Markdown.
For manual setup, follow the [quickstart](/quickstart).

## MCP server [#mcp-server]

Orbyte Credit provides a hosted, read-only MCP server. Connect it to Cursor,
Claude Code, Codex, or another client that supports Streamable HTTP and bearer
authentication. You do not need to install or run a local MCP process.

Server URL: `https://mcp.orbytelabs.com/mcp`.

### Starter prompt [#starter-prompt]

```text title="Try this after connecting"
Use Orbyte MCP to look up customer acme. Show their current balance,
list their latest usage events, and check whether they can use the images feature.
```

### Setup [#setup]

1. Open **Integration** in your application's dashboard and select the environment
   you want to inspect.
2. Under **API keys**, create a key with **Read only** permissions. Save the secret
   when it appears. You can revoke it from the same page.
3. Follow **Connect an AI assistant** on that page. It provides a Cursor install
   link and configuration for your chosen client.

The API key selects one environment. Create separate keys and connections for
production and development. Credentials belong in the `Authorization` header,
never in the MCP URL or a chat message.

For multiple active connections, use a different environment variable for each
key and update each connection's configuration to reference its own variable.

Set `ORBYTE_API_KEY` in the environment that launches your assistant. For a
terminal session:

```bash
export ORBYTE_API_KEY="YOUR_READ_ONLY_KEY"
```

Start your assistant from that session. For a desktop app, set the variable in
its launch environment and restart the app. Cursor's remote MCP configuration
does not load `.env` files automatically.

<Tabs items={["Cursor", "Claude Code", "Codex", "Other"]}>
<Tab value="Cursor">

Use **Add to Cursor** on the dashboard's Integration page, or add this to
`~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "orbyte": {
      "url": "https://mcp.orbytelabs.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:ORBYTE_API_KEY}"
      }
    }
  }
}
```

Check that `orbyte` is connected in Cursor's MCP settings.

</Tab>
<Tab value="Claude Code">

Add this to your project's `.mcp.json`:

```json
{
  "mcpServers": {
    "orbyte": {
      "type": "http",
      "url": "https://mcp.orbytelabs.com/mcp",
      "headers": {
        "Authorization": "Bearer ${ORBYTE_API_KEY}"
      }
    }
  }
}
```

Run `/mcp` in Claude Code to check the connection.

</Tab>
<Tab value="Codex">

Run this command:

```bash
codex mcp add orbyte --url https://mcp.orbytelabs.com/mcp --bearer-token-env-var ORBYTE_API_KEY
```

Check the configuration with `codex mcp list`. Codex must have access to
`ORBYTE_API_KEY` when it connects.

</Tab>
<Tab value="Other">

Use `https://mcp.orbytelabs.com/mcp` with this header:

```text
Authorization: Bearer YOUR_READ_ONLY_KEY
```

This version uses API keys. Clients that only support browser-based OAuth
connections are not supported.

</Tab>
</Tabs>

### Available tools [#available-tools]

| Tool                   | Use it to                                                                                            |
| ---------------------- | ---------------------------------------------------------------------------------------------------- |
| `list_customers`       | Find customer identities in the connected environment.                                               |
| `get_customer_balance` | Read available credits, optionally for a specific feature, and the next expiry or rollover boundary. |
| `check_feature_access` | Check whether a customer can use a feature now and read the denial reason.                           |
| `list_events`          | Browse usage by customer, feature, and date, including original charges and known costs.             |
| `get_event`            | Inspect one event's usage, original charge, allocated revenue, and margin.                           |
| `list_credit_ledger`   | Browse a customer's issued credits and consumption.                                                  |
| `get_catalog`          | Read active pricing, plans, aggregation rules, and welcome credit policies.                          |

The server exposes no write tools. It cannot issue credits, record usage, change
pricing, or create payments.

### Reading the results [#reading-the-results]

Credits and USD amounts use exact integer strings. One credit or one USD equals
`1000000000` units. Timestamps are Unix milliseconds. Event ranges include `from`
and exclude `to`.

List tools accept `limit` from 1 to 100 and a continuation `cursor`. Continue until
`isDone` is true, even if an individual filtered page is empty. Pages are not
aggregate reports.

Balances can change with expiry, rollover, or new usage. Use `asOf` and
`nextChangeAt`, and refresh before relying on an old balance. Feature-specific
balances can share the same grants, so do not add them together. An unknown
customer can preview configured welcome credits without creating a record.

Missing costs are unknown, not zero. Event revenue is allocated from consumed
grants before payment fees, refunds, and accounting adjustments. It is not net
profit. The original event payload and denied access checks are not retained as
usage history.

### Troubleshooting [#troubleshooting]

- **Unauthorized:** check the key and confirm it has not been revoked.
- **Missing permission:** each tool checks its resource's read permission.
  `list_events` also requires customer and feature read permissions for its labels.
  The **Read only** preset covers all tools; a restricted key can use the tools
  its permissions allow.
- **Environment mismatch:** remove any custom `X-Orbyte-Environment` header. The
  API key already selects its environment.
- **Variable not found:** make `ORBYTE_API_KEY` available to the process running
  your MCP client, then restart it.