Billing and AI credits

MCP Stack uses prepaid AI credits for hosted agent usage. Owners and Admins can buy top-ups through Stripe Checkout from the dashboard or CLI; Developers can view balance and history. Hosted MCP server counts may be capped by your self-serve plan.

Credit flow#

Top-ups add credits to the organization ledger; agent and hosted usage debits the balance over time.

Requirements#

• billing view access to see balance and ledger (Owners, Admins, and Developers)
• billing manage access to start checkout (Owner or Admin)
• Stripe-supported payment method for self-serve top-ups

Role details live in Organization roles and billing access.

Dashboard path#

Settings → Billing shows balance, Purchases, Usage, and hosted MCP summary.

1. Open Settings → Billing.
2. Review current AI credit balance.
3. Open Purchases for top-up history and Usage for debits.
4. Owners/Admins: click buy/top-up, complete Stripe Checkout, then sync if prompted.
5. Review hosted MCP usage summary when using hosted runtimes.

Team self-serve plans include 10 hosted MCP servers. Existing configs above the cap remain, but new hosted servers are blocked until you disable configs, upgrade, or receive an operator override.

Enterprise workspaces may show invoice status instead of self-serve plan cards.

CLI path#

Use the CLI when you want terminal-first billing, automation, or agent-led onboarding without the dashboard:

mcpstack billing status --json
mcpstack billing credits checkout --amount 50 --wait
mcpstack billing credits ledger --json

For agents and CI, use non-interactive JSON output and let the checkout command wait on server-side entitlement:

mcpstack billing credits checkout --amount 25 --non-interactive --wait --json

The command prints the Stripe Checkout URL, waits while payment is completed, and exits with refreshed billing status. Use CLI Checkout for Agents for the simple agent path. Use Billing from the CLI for full command examples and API keys for service-account automation.

API path#

Read credit summary:

GET /api/v1/organizations/{orgId}/ai-credits/summary
Authorization: Bearer {token}

Read ledger (paginated):

GET /api/v1/organizations/{orgId}/ai-credits/ledger?category=purchases&page=1&pageSize=50
GET /api/v1/organizations/{orgId}/ai-credits/ledger?category=usage&page=1&pageSize=50

Start Stripe checkout (billing manage required):

POST /api/v1/organizations/{orgId}/ai-credits/checkout-session
Authorization: Bearer {token}
Content-Type: application/json
 
{
  "amountUsd": 50
}

Sync after checkout:

POST /api/v1/organizations/{orgId}/ai-credits/checkout-session/{sessionId}/sync
Authorization: Bearer {token}

Troubleshooting#

Quick answer#

Developers see credits and usage; Owners/Admins buy top-ups from Settings → Billing or the CLI. Agent usage debits the same ledger that purchases fill.