Billing

Inspect the organization’s balance and costs with its admin permissions.

Inspect the organization’s balance and costs with its admin permissions.

These are action names. In default compact mode, call the indicated group tool with {"action":"<action-name>","params":{...}}; the arguments below go inside params. In ?mode=all, call the action name directly with those arguments. browse_github and read_docs are direct tools in both modes. Expand each schema for nested fields, enum values and validation constraints. Successful results are JSON in both text content and structuredContent; failures use isError and structuredContent.error.

Billing is per organization and requires an admin role. Pass its slug as org. MCP does not add credits or configure auto-reload; on a balance refusal, explain the entitlement and leave billing to an organization admin. MCP money errors omit payment links. REST retains checkout sessions, saved-card top-ups and auto-reload updates.

get_balance

Current balance and billing status of the caller's organization

Group: billing · Behavior: Read

Compact tool: billing · Action: get_balance

MCP annotations: readOnlyHint: true · destructiveHint: false · idempotentHint: true · openWorldHint: false

Permissions and REST equivalents

Operation	REST	Required scopes
billing.balance	GET /billing/balance	billing:read

Arguments

Argument	Type	Required	Description
org	string	No	Slug of the organization to act in (see orgs.list); needed when the caller reaches more than one

Complete input schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "org": {
      "description": "Slug of the organization to act in (see orgs.list); needed when the caller reaches more than one",
      "type": "string",
      "minLength": 3,
      "maxLength": 39
    }
  },
  "additionalProperties": false
}

Result

• balanceCents (number): Paid balance

• promoBalanceCents (number): Promotional credit, spent first

• currency (string): See the complete response schema below.

• overLimitCents (number): How far below zero the balance may go

• status (string or null): See the complete response schema below.

• mode (string): Billing mode of the organization

• frozen (boolean): The organization is frozen: writes are refused until it is unfrozen

• autoReload (object): See the complete response schema below.

Response schema: billing.balance

{
  "type": "object",
  "properties": {
    "balanceCents": {
      "type": "number",
      "description": "Paid balance"
    },
    "promoBalanceCents": {
      "type": "number",
      "description": "Promotional credit, spent first"
    },
    "currency": {
      "type": "string"
    },
    "overLimitCents": {
      "type": "number",
      "description": "How far below zero the balance may go"
    },
    "status": {
      "type": [
        "string",
        "null"
      ]
    },
    "mode": {
      "type": "string",
      "description": "Billing mode of the organization"
    },
    "frozen": {
      "type": "boolean",
      "description": "The organization is frozen: writes are refused until it is unfrozen"
    },
    "autoReload": {
      "type": "object",
      "properties": {
        "enabled": {
          "type": "boolean",
          "description": "The saved card is charged automatically when the balance drops below the threshold"
        },
        "thresholdCents": {
          "description": "Balance that triggers a reload",
          "type": [
            "number",
            "null"
          ]
        },
        "targetCents": {
          "description": "Balance after a reload",
          "type": [
            "number",
            "null"
          ]
        }
      },
      "required": [
        "enabled",
        "thresholdCents",
        "targetCents"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "balanceCents",
    "promoBalanceCents",
    "currency",
    "overLimitCents",
    "status",
    "mode",
    "frozen",
    "autoReload"
  ],
  "additionalProperties": false
}

Operation-specific errors: 400 org_required, 403 key_project_restricted.

get_costs

Cost breakdown for a date range of up to 366 days. Default: the current calendar month, UTC

Group: billing · Behavior: Read

Compact tool: billing · Action: get_costs

MCP annotations: readOnlyHint: true · destructiveHint: false · idempotentHint: true · openWorldHint: false

Permissions and REST equivalents

Operation	REST	Required scopes
billing.costs	GET /billing/costs	billing:read

Arguments

Argument	Type	Required	Description
start	string	No	First day, YYYY-MM-DD
end	string	No	Last day, YYYY-MM-DD
projectId	string	No	Limit to one project
appId	string	No	Limit to one app
org	string	No	Slug of the organization to act in (see orgs.list); needed when the caller reaches more than one

Complete input schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "start": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "First day, YYYY-MM-DD"
    },
    "end": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Last day, YYYY-MM-DD"
    },
    "projectId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{24}$",
      "description": "Limit to one project"
    },
    "appId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{24}$",
      "description": "Limit to one app"
    },
    "org": {
      "description": "Slug of the organization to act in (see orgs.list); needed when the caller reaches more than one",
      "type": "string",
      "minLength": 3,
      "maxLength": 39
    }
  },
  "additionalProperties": false
}

Result

• start (string): ISO 8601 timestamp (UTC)

• end (string): ISO 8601 timestamp (UTC)

• currency (string): See the complete response schema below.

• totalCost (number): Total for the range, in the billing currency

• byProject (array<object>): See the complete response schema below.

• byApp (array<object>): See the complete response schema below.

• byResource (array<object>): Cost per billed resource (CPU, GPU, RAM, storage, bandwidth, ...)

• daily (array<object>): See the complete response schema below.

Response schema: billing.costs

{
  "type": "object",
  "properties": {
    "start": {
      "type": "string",
      "format": "date-time",
      "description": "ISO 8601 timestamp (UTC)"
    },
    "end": {
      "type": "string",
      "format": "date-time",
      "description": "ISO 8601 timestamp (UTC)"
    },
    "currency": {
      "type": "string"
    },
    "totalCost": {
      "type": "number",
      "description": "Total for the range, in the billing currency"
    },
    "byProject": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "projectId": {
            "type": "string"
          },
          "projectName": {
            "type": "string"
          },
          "cost": {
            "type": "number"
          }
        },
        "required": [
          "projectId",
          "projectName",
          "cost"
        ],
        "additionalProperties": false
      }
    },
    "byApp": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "appId": {
            "type": "string"
          },
          "appName": {
            "type": "string"
          },
          "projectId": {
            "type": "string"
          },
          "cost": {
            "type": "number"
          }
        },
        "required": [
          "appId",
          "appName",
          "projectId",
          "cost"
        ],
        "additionalProperties": false
      }
    },
    "byResource": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string"
          },
          "cost": {
            "type": "number"
          },
          "usage": {
            "type": "number"
          },
          "unit": {
            "type": "string"
          }
        },
        "required": [
          "type",
          "cost",
          "usage",
          "unit"
        ],
        "additionalProperties": false
      },
      "description": "Cost per billed resource (CPU, GPU, RAM, storage, bandwidth, ...)"
    },
    "daily": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "date": {
            "type": "string",
            "description": "YYYY-MM-DD"
          },
          "cost": {
            "type": "number"
          }
        },
        "required": [
          "date",
          "cost"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "start",
    "end",
    "currency",
    "totalCost",
    "byProject",
    "byApp",
    "byResource",
    "daily"
  ],
  "additionalProperties": false
}

Operation-specific errors: 400 org_required.