Embedded agent budgets

Agent budgets cap hosted agent spend for embedded products. Use an agent pool for the total monthly spend ceiling, then assign per-user monthly caps for the customers in your own app. Limits use USD and reset on the first day of each UTC calendar month. When the effective cap is exhausted, new chat or realtime requests return a budget error instead of silently running without billing protection.

Concepts#

Agent usage shows monthly spend pressure, tracked external users, per-user budget source, and recent LLM calls.

The effective remaining budget for a request is the most restrictive active layer. A user can be blocked by their own cap, the agent pool, or organization credits.

Identity mapping#

The budget API externalUserId must match the identity passed to the SDK at runtime. Use your app's stable customer or account id, not an email that can change.

const externalUserId = account.id;
 
await agent.sendMessage({
  text: "Summarize my open tasks.",
  externalUserId,
  externalUser: {
    id: externalUserId,
    email: account.email,
    displayName: account.name,
    organizationId: account.organizationId,
  },
});

If the SDK sends externalUser.id, externalUserId, or an email-only identity, MCP Stack resolves that same value for tracking and enforcement. The budget mutation APIs are backend-only; never call them from browser code or expose a service-account key to the SDK client.

Service-account setup#

Create a service-account API key with a role that can edit the agent, usually developer or a custom role granted by an Owner or Admin. Store it in your backend secret manager.

mcpstack api-keys create --name checklistsquad-billing-sync --role developer --json
export MCPSTACK_API_KEY=mcpstack_sk_...
export MCPSTACK_ORG_ID=org_123
export MCPSTACK_AGENT_ID=ag_support

Send the key as either Authorization: Bearer <key> or X-API-Key: <key>. Budget reads require agent view permission; mutations require agent edit permission on the agent.

Set defaults#

Use the dedicated budget endpoint when you only need to change the pool or defaults. Existing explicit user assignments are preserved.

curl -X PATCH "https://api.mcpstack.com/api/v1/organizations/$MCPSTACK_ORG_ID/agents/$MCPSTACK_AGENT_ID/budget" \
  -H "Authorization: Bearer $MCPSTACK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "monthlyBudgetUsd": 10000,
    "defaultUserBudgetUsd": 5,
    "anonymousMonthlyBudgetUsd": 25
  }'

monthlyBudgetUsd must be greater than zero. User defaults and anonymous caps must be positive when present and cannot exceed the agent pool. Amounts accept at most two decimal places.

Signup flow#

On customer signup, your backend can either rely on the agent default or explicitly upsert the same default amount. The explicit upsert is useful when your product wants the billing system to be the source of truth.

curl -X PUT "https://api.mcpstack.com/api/v1/organizations/$MCPSTACK_ORG_ID/agents/$MCPSTACK_AGENT_ID/external-users/customer_abc/budget" \
  -H "Authorization: Bearer $MCPSTACK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "monthlyBudgetUsd": 5 }'

The call is idempotent. Retrying a signup webhook with the same externalUserId updates the same user budget record and returns the current budget and spend. If you only configure defaultUserBudgetUsd, MCP Stack creates a default assignment the first time an identified user chats.

Upgrade flow#

When a customer upgrades or support changes their allowance, call the same upsert endpoint with the new cap.

curl -X PUT "https://api.mcpstack.com/api/v1/organizations/$MCPSTACK_ORG_ID/agents/$MCPSTACK_AGENT_ID/external-users/customer_abc/budget" \
  -H "Authorization: Bearer $MCPSTACK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "monthlyBudgetUsd": 25 }'

To remove the explicit cap and fall back to the agent default:

curl -X DELETE "https://api.mcpstack.com/api/v1/organizations/$MCPSTACK_ORG_ID/agents/$MCPSTACK_AGENT_ID/external-users/customer_abc/budget" \
  -H "Authorization: Bearer $MCPSTACK_API_KEY"

Read usage#

Read one user's budget and current UTC-month usage:

curl "https://api.mcpstack.com/api/v1/organizations/$MCPSTACK_ORG_ID/agents/$MCPSTACK_AGENT_ID/external-users/customer_abc/budget" \
  -H "Authorization: Bearer $MCPSTACK_API_KEY"

Read the agent usage overview, including tracked users and recent LLM calls:

curl "https://api.mcpstack.com/api/v1/organizations/$MCPSTACK_ORG_ID/agents/$MCPSTACK_AGENT_ID/usage" \
  -H "Authorization: Bearer $MCPSTACK_API_KEY"

User status values are:

CLI path#

The CLI mirrors the API for operator tasks and debugging. Use API calls from production signup and billing code; use CLI commands for imports, support checks, and manual recovery.

mcpstack agents budget defaults ag_support --monthly-usd 10000 --default-user-usd 5 --json
mcpstack agents budget set ag_support --user customer_abc --monthly-usd 5 --json
mcpstack agents budget get ag_support --user customer_abc --json
mcpstack agents usage ag_support --json

Error handling#

Common API errors:

ChecklistSquad-style walkthrough#

1. Configure the assistant with a $10,000 agent pool and $5 default user budget.
2. On Todo signup, call PUT .../external-users/{externalUserId}/budget with { "monthlyBudgetUsd": 5 }.
3. Pass the same externalUserId to the embedded SDK when the customer chats.
4. If the user spends through $5, chat returns user_budget_exhausted.
5. When the customer upgrades, call the same PUT endpoint with { "monthlyBudgetUsd": 25 }.
6. Use GET .../usage or mcpstack agents usage to monitor warning and blocked users.

Related#

• Embed an agent with app auth
• API keys and service accounts
• Billing and AI credits

Quick answer#

Set the agent pool with PATCH .../budget, set user caps with PUT .../external-users/{externalUserId}/budget, and pass the same externalUserId from the SDK. Budget mutation is a backend service-account workflow.