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:
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/orbytelabsThe 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 | Inspect the project and choose the workflow. |
| orbyte-setup | Create and deploy orbyte.config.ts, link an environment, and configure a server key. |
| orbyte-integrate | Connect and verify real usage tracking. |
| orbyte-migrate | 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.
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
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
- Open Integration in your application's dashboard and select the environment you want to inspect.
- Under API keys, create a key with Read only permissions. Save the secret when it appears. You can revoke it from the same page.
- 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
| 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
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_eventsalso 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-Environmentheader. The API key already selects its environment. - Variable not found: make
ORBYTE_API_KEYavailable to the process running your MCP client, then restart it.
