Invoices and payment settings

Read invoices and ledger history, manage saved cards, redeem vouchers and configure node protection.

Read invoices and ledger history, manage saved cards, redeem vouchers and configure node protection.

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.

list_invoices

List the organization's monthly invoices, newest first. Optionally for one month, status or date range

Group: billing · Behavior: Read

Compact tool: billing · Action: list_invoices

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

Permissions and REST equivalents

Operation	REST	Required scopes
billing.invoices.list	GET /billing/invoices	billing:read

Arguments

Argument	Type	Required	Description
year	integer	No	Invoices of one year
month	integer	No	Invoices of one month (with year)
status	"draft" / "finalized" / "paid"	No	Invoices in this state
from	string	No	Billing periods starting on or after this day, YYYY-MM-DD
to	string	No	Billing periods ending on or before this day, YYYY-MM-DD
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": {
    "year": {
      "type": "integer",
      "minimum": 2020,
      "maximum": 2100,
      "description": "Invoices of one year"
    },
    "month": {
      "type": "integer",
      "minimum": 1,
      "maximum": 12,
      "description": "Invoices of one month (with year)"
    },
    "status": {
      "type": "string",
      "enum": [
        "draft",
        "finalized",
        "paid"
      ],
      "description": "Invoices in this state"
    },
    "from": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Billing periods starting on or after this day, YYYY-MM-DD"
    },
    "to": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Billing periods ending on or before this day, YYYY-MM-DD"
    },
    "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

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

Response schema: billing.invoices.list

{
  "type": "object",
  "properties": {
    "invoices": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "number": {
            "type": "string",
            "description": "Invoice number; what the other invoice operations take"
          },
          "period": {
            "type": "object",
            "properties": {
              "start": {
                "type": "string",
                "description": "YYYY-MM-DD"
              },
              "end": {
                "type": "string",
                "description": "YYYY-MM-DD"
              }
            },
            "required": [
              "start",
              "end"
            ],
            "additionalProperties": false,
            "description": "Billing period, inclusive"
          },
          "status": {
            "type": "string",
            "enum": [
              "draft",
              "finalized",
              "paid"
            ]
          },
          "partialMonth": {
            "type": "boolean",
            "description": "The organization's billing began during the period"
          },
          "currency": {
            "type": "string"
          },
          "totalCents": {
            "type": "integer",
            "description": "Usage charged in the period"
          },
          "amountDueCents": {
            "type": "integer",
            "description": "What the organization owes on this invoice; 0 when credit covered it"
          },
          "closingBalanceCents": {
            "type": "integer",
            "description": "Balance at the end of the period; negative means owed"
          },
          "createdOn": {
            "type": "string",
            "description": "YYYY-MM-DD"
          },
          "updatedOn": {
            "anyOf": [
              {
                "type": "string",
                "description": "YYYY-MM-DD"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "number",
          "period",
          "status",
          "partialMonth",
          "currency",
          "totalCents",
          "amountDueCents",
          "closingBalanceCents",
          "createdOn",
          "updatedOn"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "invoices"
  ],
  "additionalProperties": false
}

Operation-specific errors: 400 org_required, 403 key_project_restricted.

get_invoice

Get one invoice with its summary, itemized usage, payments and credits. The PDF is only available through the REST API (GET /v1/billing/invoices/{invoiceNumber}/pdf).

Group: billing · Behavior: Read

Compact tool: billing · Action: get_invoice

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

Permissions and REST equivalents

Operation	REST	Required scopes
billing.invoices.get	GET /billing/invoices/{invoiceNumber}	billing:read

Arguments

Argument	Type	Required	Description
invoiceNumber	string	Yes	Invoice number
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": {
    "invoiceNumber": {
      "type": "string",
      "minLength": 1,
      "description": "Invoice number"
    },
    "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
    }
  },
  "required": [
    "invoiceNumber"
  ],
  "additionalProperties": false
}

Result

• number (string): Invoice number; what the other invoice operations take

• period (object): Billing period, inclusive

• status ("draft" / "finalized" / "paid"): See the complete response schema below.

• partialMonth (boolean): The organization's billing began during the period

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

• totalCents (integer): Usage charged in the period

• amountDueCents (integer): What the organization owes on this invoice; 0 when credit covered it

• closingBalanceCents (integer): Balance at the end of the period; negative means owed

• createdOn (string): YYYY-MM-DD

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

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

• statement (object): The statement summary: how the balance moved over the period

• items (array<object>): Itemized usage

• credits (array<object>): Payments, promos, refunds and adjustments within the period

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

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

Response schema: billing.invoices.get

{
  "type": "object",
  "properties": {
    "number": {
      "type": "string",
      "description": "Invoice number; what the other invoice operations take"
    },
    "period": {
      "type": "object",
      "properties": {
        "start": {
          "type": "string",
          "description": "YYYY-MM-DD"
        },
        "end": {
          "type": "string",
          "description": "YYYY-MM-DD"
        }
      },
      "required": [
        "start",
        "end"
      ],
      "additionalProperties": false,
      "description": "Billing period, inclusive"
    },
    "status": {
      "type": "string",
      "enum": [
        "draft",
        "finalized",
        "paid"
      ]
    },
    "partialMonth": {
      "type": "boolean",
      "description": "The organization's billing began during the period"
    },
    "currency": {
      "type": "string"
    },
    "totalCents": {
      "type": "integer",
      "description": "Usage charged in the period"
    },
    "amountDueCents": {
      "type": "integer",
      "description": "What the organization owes on this invoice; 0 when credit covered it"
    },
    "closingBalanceCents": {
      "type": "integer",
      "description": "Balance at the end of the period; negative means owed"
    },
    "createdOn": {
      "type": "string",
      "description": "YYYY-MM-DD"
    },
    "updatedOn": {
      "anyOf": [
        {
          "type": "string",
          "description": "YYYY-MM-DD"
        },
        {
          "type": "null"
        }
      ]
    },
    "customer": {
      "type": "object",
      "properties": {
        "email": {
          "type": "string"
        },
        "name": {
          "type": [
            "string",
            "null"
          ]
        },
        "billingEmail": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "email",
        "name",
        "billingEmail"
      ],
      "additionalProperties": false
    },
    "statement": {
      "type": "object",
      "properties": {
        "openingBalanceCents": {
          "type": "integer"
        },
        "closingBalanceCents": {
          "type": "integer"
        },
        "amountDueCents": {
          "type": "integer"
        },
        "paymentsCents": {
          "type": "integer",
          "description": "Card and off-platform payments received in the period"
        },
        "promosCents": {
          "type": "integer",
          "description": "Promotional credit granted in the period"
        },
        "refundsCents": {
          "type": "integer",
          "description": "Signed"
        },
        "adjustmentsCents": {
          "type": "integer",
          "description": "Signed"
        },
        "usageCents": {
          "type": "integer",
          "description": "Usage charged in the period"
        },
        "taxCents": {
          "type": "integer",
          "description": "Tax due on the amount owed; 0 when nothing is owed or no rate applies"
        },
        "taxRateBps": {
          "type": "integer",
          "description": "Tax rate the invoice was billed under, in basis points"
        }
      },
      "required": [
        "openingBalanceCents",
        "closingBalanceCents",
        "amountDueCents",
        "paymentsCents",
        "promosCents",
        "refundsCents",
        "adjustmentsCents",
        "usageCents",
        "taxCents",
        "taxRateBps"
      ],
      "additionalProperties": false,
      "description": "The statement summary: how the balance moved over the period"
    },
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "resource": {
            "type": "string",
            "description": "What was billed, e.g. a GPU model, RAM, storage, a server"
          },
          "detail": {
            "type": [
              "string",
              "null"
            ]
          },
          "csp": {
            "type": [
              "string",
              "null"
            ]
          },
          "region": {
            "type": [
              "string",
              "null"
            ]
          },
          "zone": {
            "type": [
              "string",
              "null"
            ]
          },
          "kcRegion": {
            "type": [
              "string",
              "null"
            ]
          },
          "quantity": {
            "type": "number"
          },
          "unit": {
            "type": "string"
          },
          "unitPrice": {
            "type": "number",
            "description": "Price per unit, in currency units (fractional)"
          },
          "amount": {
            "type": "number",
            "description": "quantity times unitPrice, in currency units"
          }
        },
        "required": [
          "resource",
          "detail",
          "csp",
          "region",
          "zone",
          "kcRegion",
          "quantity",
          "unit",
          "unitPrice",
          "amount"
        ],
        "additionalProperties": false
      },
      "description": "Itemized usage"
    },
    "credits": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "ledgerEntryId": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "description": "Ledger entry type: credit_topup, manual_payment, a promo, refund, adjustment"
          },
          "at": {
            "type": "string",
            "description": "ISO 8601 timestamp"
          },
          "amountCents": {
            "type": "integer",
            "description": "Signed"
          },
          "label": {
            "type": "string"
          },
          "paymentMethod": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "brand": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "last4": {
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "required": [
                  "brand",
                  "last4"
                ],
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "ledgerEntryId",
          "type",
          "at",
          "amountCents",
          "label",
          "paymentMethod"
        ],
        "additionalProperties": false
      },
      "description": "Payments, promos, refunds and adjustments within the period"
    },
    "finalizedOn": {
      "anyOf": [
        {
          "type": "string",
          "description": "YYYY-MM-DD"
        },
        {
          "type": "null"
        }
      ]
    },
    "paidOn": {
      "anyOf": [
        {
          "type": "string",
          "description": "YYYY-MM-DD"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "number",
    "period",
    "status",
    "partialMonth",
    "currency",
    "totalCents",
    "amountDueCents",
    "closingBalanceCents",
    "createdOn",
    "updatedOn",
    "customer",
    "statement",
    "items",
    "credits",
    "finalizedOn",
    "paidOn"
  ],
  "additionalProperties": false
}

Operation-specific errors: 400 org_required, 403 key_project_restricted.

list_charges

Usage charges summed per day or per hour, newest first. From the ledger, with the split between serverless apps, dedicated servers and spot leases

Group: billing · Behavior: Read

Compact tool: billing · Action: list_charges

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

Permissions and REST equivalents

Operation	REST	Required scopes
billing.charges.list	GET /billing/charges	billing:read

Arguments

Argument	Type	Required	Description
granularity	"day" / "hour"	No	Sum per day (default) or per hour
from	string	No	First day to include, YYYY-MM-DD
to	string	No	Last day to include, YYYY-MM-DD
timeZone	string	No	IANA time zone the days are counted in, e.g. America/Los_Angeles; UTC by default
limit	integer	No	Items per page, 1 to 200 (default 50)
cursor	string	No	nextCursor from the previous page; omit for the first page
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": {
    "granularity": {
      "type": "string",
      "enum": [
        "day",
        "hour"
      ],
      "description": "Sum per day (default) or per hour"
    },
    "from": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "First day to include, YYYY-MM-DD"
    },
    "to": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Last day to include, YYYY-MM-DD"
    },
    "timeZone": {
      "type": "string",
      "description": "IANA time zone the days are counted in, e.g. America/Los_Angeles; UTC by default"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 200,
      "description": "Items per page, 1 to 200 (default 50)"
    },
    "cursor": {
      "type": "string",
      "minLength": 1,
      "maxLength": 512,
      "description": "nextCursor from the previous page; omit for the first page"
    },
    "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

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

• nextCursor (string or null): Pass as cursor to fetch the next page; null on the last page

Response schema: billing.charges.list

{
  "type": "object",
  "properties": {
    "charges": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "period": {
            "type": "string",
            "format": "date-time",
            "description": "Start of the day or hour, in the requested time zone"
          },
          "amountCents": {
            "type": "number",
            "description": "Usage charged in the period, including fractional cents"
          },
          "appsCents": {
            "type": "number",
            "description": "Of amountCents, serverless app usage"
          },
          "serversCents": {
            "type": "number",
            "description": "Of amountCents, dedicated servers"
          },
          "spotCents": {
            "type": "number",
            "description": "Of amountCents, spot leases"
          },
          "currency": {
            "type": "string"
          }
        },
        "required": [
          "period",
          "amountCents",
          "appsCents",
          "serversCents",
          "spotCents",
          "currency"
        ],
        "additionalProperties": false
      }
    },
    "nextCursor": {
      "description": "Pass as cursor to fetch the next page; null on the last page",
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "charges",
    "nextCursor"
  ],
  "additionalProperties": false
}

Operation-specific errors: 400 org_required, 403 key_project_restricted.

list_credits

Ledger entries that added or removed credit, newest first. Payments, promotional credit, refunds, adjustments

Group: billing · Behavior: Read

Compact tool: billing · Action: list_credits

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

Permissions and REST equivalents

Operation	REST	Required scopes
billing.credits.list	GET /billing/credits	billing:read

Arguments

Argument	Type	Required	Description
type	"credit_topup" / "manual_payment" / "signup_promo" / "credit_promo" / "social_media_promo" / "refund" / "adjustment"	No	Only entries of this type
from	string	No	First day to include, YYYY-MM-DD (UTC)
to	string	No	Last day to include, YYYY-MM-DD (UTC)
limit	integer	No	Items per page, 1 to 200 (default 50)
cursor	string	No	nextCursor from the previous page; omit for the first page
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": {
    "type": {
      "type": "string",
      "enum": [
        "credit_topup",
        "manual_payment",
        "signup_promo",
        "credit_promo",
        "social_media_promo",
        "refund",
        "adjustment"
      ],
      "description": "Only entries of this type"
    },
    "from": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "First day to include, YYYY-MM-DD (UTC)"
    },
    "to": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Last day to include, YYYY-MM-DD (UTC)"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 200,
      "description": "Items per page, 1 to 200 (default 50)"
    },
    "cursor": {
      "type": "string",
      "minLength": 1,
      "maxLength": 512,
      "description": "nextCursor from the previous page; omit for the first page"
    },
    "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

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

• nextCursor (string or null): Pass as cursor to fetch the next page; null on the last page

Response schema: billing.credits.list

{
  "type": "object",
  "properties": {
    "entries": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Ledger entry id"
          },
          "at": {
            "type": "string",
            "format": "date-time",
            "description": "ISO 8601 timestamp (UTC)"
          },
          "type": {
            "type": "string",
            "enum": [
              "credit_topup",
              "manual_payment",
              "signup_promo",
              "credit_promo",
              "social_media_promo",
              "refund",
              "adjustment"
            ],
            "description": "credit_topup and manual_payment are money in; the promos are granted credit"
          },
          "amountCents": {
            "type": "integer",
            "description": "Signed: positive adds credit, negative removes it"
          },
          "currency": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "description": "succeeded, pending or failed"
          },
          "paymentMethod": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "brand": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "last4": {
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "required": [
                  "brand",
                  "last4"
                ],
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ],
            "description": "The card charged, for card payments"
          },
          "note": {
            "description": "A note left by the person who recorded a manual entry",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "id",
          "at",
          "type",
          "amountCents",
          "currency",
          "status",
          "paymentMethod",
          "note"
        ],
        "additionalProperties": false
      }
    },
    "nextCursor": {
      "description": "Pass as cursor to fetch the next page; null on the last page",
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "entries",
    "nextCursor"
  ],
  "additionalProperties": false
}

Operation-specific errors: 400 org_required, 403 key_project_restricted.

list_payment_methods

List the organization's saved cards and which one is the default

Group: billing · Behavior: Read

Compact tool: billing · Action: list_payment_methods

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

Permissions and REST equivalents

Operation	REST	Required scopes
billing.paymentMethods.list	GET /billing/payment-methods	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

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

Response schema: billing.paymentMethods.list

{
  "type": "object",
  "properties": {
    "paymentMethods": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Payment method id"
          },
          "brand": {
            "description": "Card brand, e.g. visa",
            "type": [
              "string",
              "null"
            ]
          },
          "last4": {
            "type": [
              "string",
              "null"
            ]
          },
          "expMonth": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ]
          },
          "expYear": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ]
          },
          "default": {
            "type": "boolean",
            "description": "The card auto-reload and top-ups charge"
          },
          "addedAt": {
            "type": "string",
            "format": "date-time",
            "description": "ISO 8601 timestamp (UTC)"
          }
        },
        "required": [
          "id",
          "brand",
          "last4",
          "expMonth",
          "expYear",
          "default",
          "addedAt"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "paymentMethods"
  ],
  "additionalProperties": false
}

Operation-specific errors: 400 org_required, 403 key_project_restricted.

set_default_payment_method

Make a saved card the default for auto-reload and top-ups

Group: billing · Behavior: Write

Compact tool: billing_write · Action: set_default_payment_method

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

Permissions and REST equivalents

Operation	REST	Required scopes
billing.paymentMethods.setDefault	POST /billing/payment-methods/{paymentMethodId}/default	billing:write

Arguments

Argument	Type	Required	Description
paymentMethodId	string	Yes	Payment method id from the list
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": {
    "paymentMethodId": {
      "type": "string",
      "minLength": 1,
      "description": "Payment method id from the list"
    },
    "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
    }
  },
  "required": [
    "paymentMethodId"
  ],
  "additionalProperties": false
}

Result

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

Response schema: billing.paymentMethods.setDefault

{
  "type": "object",
  "properties": {
    "paymentMethods": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Payment method id"
          },
          "brand": {
            "description": "Card brand, e.g. visa",
            "type": [
              "string",
              "null"
            ]
          },
          "last4": {
            "type": [
              "string",
              "null"
            ]
          },
          "expMonth": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ]
          },
          "expYear": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ]
          },
          "default": {
            "type": "boolean",
            "description": "The card auto-reload and top-ups charge"
          },
          "addedAt": {
            "type": "string",
            "format": "date-time",
            "description": "ISO 8601 timestamp (UTC)"
          }
        },
        "required": [
          "id",
          "brand",
          "last4",
          "expMonth",
          "expYear",
          "default",
          "addedAt"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "paymentMethods"
  ],
  "additionalProperties": false
}

Operation-specific errors: 404 not_found, 400 org_required, 403 key_project_restricted.

remove_payment_method

Remove a saved card. A removed default is replaced by the next saved card; auto-reload is switched off when no card is left.

Group: billing · Behavior: Write

Compact tool: billing_write · Action: remove_payment_method

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

Requires confirm: true for this irreversible action.

Permissions and REST equivalents

Operation	REST	Required scopes
billing.paymentMethods.remove	DELETE /billing/payment-methods/{paymentMethodId}	billing:write

Arguments

Argument	Type	Required	Description
paymentMethodId	string	Yes	Payment method id from the list
confirm	true	Yes	Must be true: this action cannot be undone
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": {
    "paymentMethodId": {
      "type": "string",
      "minLength": 1,
      "description": "Payment method id from the list"
    },
    "confirm": {
      "type": "boolean",
      "const": true,
      "description": "Must be true: this action cannot be undone"
    },
    "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
    }
  },
  "required": [
    "paymentMethodId",
    "confirm"
  ],
  "additionalProperties": false
}

Result

• paymentMethods (array<object>): The cards that remain

• autoReloadDisabled (boolean): Auto-reload was switched off because no card is left

Response schema: billing.paymentMethods.remove

{
  "type": "object",
  "properties": {
    "paymentMethods": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Payment method id"
          },
          "brand": {
            "description": "Card brand, e.g. visa",
            "type": [
              "string",
              "null"
            ]
          },
          "last4": {
            "type": [
              "string",
              "null"
            ]
          },
          "expMonth": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ]
          },
          "expYear": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ]
          },
          "default": {
            "type": "boolean",
            "description": "The card auto-reload and top-ups charge"
          },
          "addedAt": {
            "type": "string",
            "format": "date-time",
            "description": "ISO 8601 timestamp (UTC)"
          }
        },
        "required": [
          "id",
          "brand",
          "last4",
          "expMonth",
          "expYear",
          "default",
          "addedAt"
        ],
        "additionalProperties": false
      },
      "description": "The cards that remain"
    },
    "autoReloadDisabled": {
      "type": "boolean",
      "description": "Auto-reload was switched off because no card is left"
    }
  },
  "required": [
    "paymentMethods",
    "autoReloadDisabled"
  ],
  "additionalProperties": false
}

Operation-specific errors: 404 not_found, 400 org_required, 403 key_project_restricted.

redeem_voucher

Redeem a voucher code for organization credit; once per person per code

Group: billing · Behavior: Write

Compact tool: billing_write · Action: redeem_voucher

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

Permissions and REST equivalents

Operation	REST	Required scopes
billing.vouchers.redeem	POST /billing/vouchers/redeem	billing:write

Arguments

Argument	Type	Required	Description
code	string	Yes	The voucher code
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": {
    "code": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "description": "The voucher code"
    },
    "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
    }
  },
  "required": [
    "code"
  ],
  "additionalProperties": false
}

Result

• amountCents (integer): Credit added to the balance

• redemptionsRemaining (integer or null): Uses the voucher has left

Response schema: billing.vouchers.redeem

{
  "type": "object",
  "properties": {
    "amountCents": {
      "type": "integer",
      "description": "Credit added to the balance"
    },
    "redemptionsRemaining": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "description": "Uses the voucher has left"
    }
  },
  "required": [
    "amountCents",
    "redemptionsRemaining"
  ],
  "additionalProperties": false
}

Operation-specific errors: 404 voucher_not_found, 400 voucher_rejected, 429 too_many_attempts, 400 org_required, 403 key_project_restricted.

get_node_protection

Read the organization's node protection setting. Whether its dedicated servers are hibernated automatically when the balance is about to run out, and at how many hours of runway

Group: billing · Behavior: Read

Compact tool: billing · Action: get_node_protection

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

Permissions and REST equivalents

Operation	REST	Required scopes
billing.nodeProtection.get	GET /billing/node-protection	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

• enabled (boolean): The organization's dedicated servers are hibernated when the balance runs low

• thresholdHours (integer or null): Hours of runway left (balance over spend rate) at which the servers are hibernated; null when off

• hibernatedAt (string or null): When protection last hibernated the servers

• deprovisionedAt (string or null): When a balance past its limit last deprovisioned them

Response schema: billing.nodeProtection.get

{
  "type": "object",
  "properties": {
    "enabled": {
      "type": "boolean",
      "description": "The organization's dedicated servers are hibernated when the balance runs low"
    },
    "thresholdHours": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "description": "Hours of runway left (balance over spend rate) at which the servers are hibernated; null when off"
    },
    "hibernatedAt": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time",
          "description": "ISO 8601 timestamp (UTC)"
        },
        {
          "type": "null"
        }
      ],
      "description": "When protection last hibernated the servers"
    },
    "deprovisionedAt": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time",
          "description": "ISO 8601 timestamp (UTC)"
        },
        {
          "type": "null"
        }
      ],
      "description": "When a balance past its limit last deprovisioned them"
    }
  },
  "required": [
    "enabled",
    "thresholdHours",
    "hibernatedAt",
    "deprovisionedAt"
  ],
  "additionalProperties": false
}

Operation-specific errors: 400 org_required, 403 key_project_restricted.

set_node_protection

Turn node protection on with a runway threshold, or off. On: when the balance would run out within thresholdHours at the current spend rate, the organization's dedicated servers are hibernated (storage only) until credits are added.

Group: billing · Behavior: Write

Compact tool: billing_write · Action: set_node_protection

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

Permissions and REST equivalents

Operation	REST	Required scopes
billing.nodeProtection.update	PATCH /billing/node-protection	billing:write

Arguments

Argument	Type	Required	Description
enabled	boolean	Yes	Turn protection on or off
thresholdHours	integer	No	Hours of runway that trigger hibernation, 2 to 48; required when enabling
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": {
    "enabled": {
      "type": "boolean",
      "description": "Turn protection on or off"
    },
    "thresholdHours": {
      "type": "integer",
      "minimum": 2,
      "maximum": 48,
      "description": "Hours of runway that trigger hibernation, 2 to 48; required when enabling"
    },
    "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
    }
  },
  "required": [
    "enabled"
  ],
  "additionalProperties": false
}

Result

• enabled (boolean): The organization's dedicated servers are hibernated when the balance runs low

• thresholdHours (integer or null): Hours of runway left (balance over spend rate) at which the servers are hibernated; null when off

• hibernatedAt (string or null): When protection last hibernated the servers

• deprovisionedAt (string or null): When a balance past its limit last deprovisioned them

Response schema: billing.nodeProtection.update

{
  "type": "object",
  "properties": {
    "enabled": {
      "type": "boolean",
      "description": "The organization's dedicated servers are hibernated when the balance runs low"
    },
    "thresholdHours": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "description": "Hours of runway left (balance over spend rate) at which the servers are hibernated; null when off"
    },
    "hibernatedAt": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time",
          "description": "ISO 8601 timestamp (UTC)"
        },
        {
          "type": "null"
        }
      ],
      "description": "When protection last hibernated the servers"
    },
    "deprovisionedAt": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time",
          "description": "ISO 8601 timestamp (UTC)"
        },
        {
          "type": "null"
        }
      ],
      "description": "When a balance past its limit last deprovisioned them"
    }
  },
  "required": [
    "enabled",
    "thresholdHours",
    "hibernatedAt",
    "deprovisionedAt"
  ],
  "additionalProperties": false
}

Operation-specific errors: 400 org_required, 403 key_project_restricted.