Billing from the CLI
Buy AI credits, upgrade hosted MCP, wait for checkout completion, and read billing state without opening the dashboard.
The mcpstack CLI can manage MCP Stack billing from a terminal. Owners and Admins can start Stripe Checkout. Developers can inspect balance, ledger history, and hosted usage when their organization role includes billing view access.
mcpstack auth login for a human operator, or MCPSTACK_API_KEY for service-account automationRole details live in Organization roles and billing access.
If an agent needs the shortest checkout path, use CLI Checkout for Agents.
mcpstack billing status --json
mcpstack billing plans list --json
mcpstack billing credits ledger --jsonbilling status reports the active hosted MCP plan, AI credit balance, and credit settings that the CLI can read. Use --org <id> or MCPSTACK_ORG_ID when your login can access multiple organizations.
Interactive checkout opens Stripe for the operator:
mcpstack billing credits checkout --amount 50 --waitNon-interactive checkout can wait in one command while an agent or CI runner completes Stripe in its own browser flow:
mcpstack billing credits checkout --amount 25 --non-interactive --wait --jsonThe command prints a Stripe Checkout URL immediately, waits while payment is completed, and returns final JSON after the organization balance is refreshed. If your runner cannot keep the process open, omit --wait, complete the printed Stripe URL, and run billing wait.
After completion, inspect the purchase ledger:
mcpstack billing credits ledger --jsonList available self-serve plans:
mcpstack billing plans listStart checkout:
mcpstack billing checkout --plan mcp_hosting_team --waitFor automation:
mcpstack billing checkout --plan mcp_hosting_team --non-interactive --wait --jsonComplete the printed Stripe URL while the command waits. Only split checkout and waiting when your runner cannot keep the process open.
Some organizations can buy prepaid hosted tool-call credits:
mcpstack billing tool-call-credits checkout --calls 100000 --non-interactive --wait --json
mcpstack billing tool-call-credits ledger --jsonComplete the printed Stripe URL while the command waits. Only split checkout and waiting when your runner cannot keep the process open.
MCP Stack fulfills hosted checkout through Stripe webhooks. billing sync exists as an idempotent fallback for local development and delayed webhook delivery:
mcpstack billing sync cs_... --product ai-credits --jsonUse billing wait first. Normal hosted checkout does not require a separate sync step.
| Symptom | What to check |
|---|---|
HTTP 401 | Sign in again or set a valid MCPSTACK_API_KEY. |
HTTP 403 | Your role lacks billing view or billing manage access. |
billing wait times out | Check the Stripe checkout session, webhook delivery, and --product value. |
| Balance did not change | Run billing credits ledger --json; if empty, ask an Owner/Admin to inspect webhook delivery. |
Use billing credits checkout --amount 50 --wait for an operator checkout. Agents and CI should use --non-interactive --wait --json, complete the printed Stripe URL, and read the final JSON from the same command.