Skip to Content
Orbyte Labs

Agents & MCP

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 to investigate existing customer data.

Set up with an agent

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

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

From your application's directory:

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.

SkillPurpose
orbyte-onboardInspect the project and choose the workflow.
orbyte-setupCreate and deploy orbyte.config.ts, link an environment, and configure a server key.
orbyte-integrateConnect and verify real usage tracking.
orbyte-migratePreserve 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.

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

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

  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:

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.

Use Add to Cursor on the dashboard's Integration page, or add this to ~/.cursor/mcp.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.

Available tools

ToolUse it to
list_customersFind customer identities in the connected environment.
get_customer_balanceRead available credits, optionally for a specific feature, and the next expiry or rollover boundary.
check_feature_accessCheck whether a customer can use a feature now and read the denial reason.
list_eventsBrowse usage by customer, feature, and date, including original charges and known costs.
get_eventInspect one event's usage, original charge, allocated revenue, and margin.
list_credit_ledgerBrowse a customer's issued credits and consumption.
get_catalogRead 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

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

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

On this page