Meterbox MCP server

Meterbox's hosted MCP server connects an AI assistant (Claude, ChatGPT, Claude Code, Cursor, VS Code or Codex) to your Meterbox account. The assistant can look up and manage your plans, models, customers, usage, credits, invoices and the rest of your billing setup through the same API your backend uses (API reference).

You need a Meterbox account. Each connection acts on one environment of one organization, and an owner or admin of that organization approves it.

Endpoints

Environment URL What it reaches
Sandbox https://meterbox.ai/mcp/sandbox Your sandbox environment and test data. Changes run directly.
Production https://meterbox.ai/mcp/production Your live environment. Read-only, or every change waits for an owner's or admin's approval.

Both use the Streamable HTTP transport (POST only, no session), and Meterbox's OAuth 2.1 authorization server for sign-in. On a self-managed deployment, use your own host in place of meterbox.ai.

MCP access is on for both environments by default. An owner or admin can turn it off for either one under Settings > API keys.

Connect

Claude and ChatGPT

  1. Add https://meterbox.ai/mcp/sandbox (or /mcp/production) as a custom connector.
  2. Sign in to Meterbox when asked.
  3. An owner or admin of the organization approves the connection and picks its access: read-only, read and write (sandbox), or propose changes (production).

The connection lasts 90 days and shows under Settings > API keys > Connected apps, where you can disconnect it at any time.

Claude Code, Cursor, VS Code, Codex and other clients

These clients connect with an agent key. Create one under Settings > API keys: choose the environment, read-only or write access, optionally the toolsets it may use, and an expiry (90 days by default). Keep the key in an environment variable so it never lands in a config file:

export METERBOX_SANDBOX_AGENT_KEY=mb_agent_sandbox_...

Claude Code (.mcp.json):

{
  "mcpServers": {
    "meterbox-sandbox": {
      "type": "http",
      "url": "https://meterbox.ai/mcp/sandbox",
      "headers": { "Authorization": "Bearer ${METERBOX_SANDBOX_AGENT_KEY}" }
    }
  }
}

Cursor (~/.cursor/mcp.json):

{
  "mcpServers": {
    "meterbox-sandbox": {
      "url": "https://meterbox.ai/mcp/sandbox",
      "headers": { "Authorization": "Bearer ${env:METERBOX_SANDBOX_AGENT_KEY}" }
    }
  }
}

VS Code (.vscode/mcp.json, which prompts for the key and stores it securely):

{
  "inputs": [
    {
      "type": "promptString",
      "id": "meterbox-sandbox-key",
      "description": "Meterbox sandbox agent key",
      "password": true
    }
  ],
  "servers": {
    "meterbox-sandbox": {
      "type": "http",
      "url": "https://meterbox.ai/mcp/sandbox",
      "headers": { "Authorization": "Bearer ${input:meterbox-sandbox-key}" }
    }
  }
}

Codex:

codex mcp add meterbox-sandbox --url https://meterbox.ai/mcp/sandbox --bearer-token-env-var METERBOX_SANDBOX_AGENT_KEY

Clients that only run local commands can use the stdio bridge, @meterbox/mcp, which forwards to the same endpoint:

{
  "mcpServers": {
    "meterbox-sandbox": {
      "command": "npx",
      "args": ["-y", "@meterbox/mcp"],
      "env": {
        "METERBOX_BASE_URL": "https://meterbox.ai",
        "METERBOX_AGENT_KEY": "${METERBOX_SANDBOX_AGENT_KEY}"
      }
    }
  }
}

API keys (mb_live_...) don't work with MCP: use an agent key or sign in.

What a connection can do

Access Environment What it can do
Read-only Both Look things up. Never changes anything.
Read and write Sandbox Create and change records. Irreversible or money-moving operations (deletes, credit notes, invoice approval, month-end close and the like) also run, but only while the sandbox's billing provider is in test mode, and they're marked so your client asks you first.
Propose changes Production Each create or update becomes a pending change that an owner or admin approves or rejects under Settings > API keys > Pending changes within 24 hours; it only runs once approved. Irreversible or money-moving operations never run in production over MCP.

Money only ever moves in sandbox, against a payment provider in test mode. Every change that runs is recorded in your audit log first.

Tools

The server has seven tools. A connection only sees the tools its access allows, and each run tool only accepts operations of its own kind, so a read-only tool can never make a change.

Tool Title Annotations What it does
meterbox_whoami Show connection details read-only Which environment the connection acts on, whether it can make changes, and its toolsets and tools.
meterbox_search_operations Search Meterbox operations read-only Finds API operations by keyword, toolset or kind.
meterbox_describe_operation Describe a Meterbox operation read-only Shows one operation's parameters and request body.
meterbox_read Read from Meterbox read-only Runs a lookup: a read, or a preview, quote, validation or simulation that changes nothing.
meterbox_create Create in Meterbox write Runs an operation that only adds a record, such as a coupon, a quote or an alert rule.
meterbox_update Change records in Meterbox write, destructive Runs an operation that changes existing records or settings, such as replacing a plan. Never moves money.
meterbox_destructive Irreversible or money-moving change write, destructive Runs an irreversible or money-moving operation. Sandbox only, and the client confirms it with you first.

Toolsets

Operations are grouped into toolsets: accounting, alerts, anomalies, billing, catalog, coupons, credits, customers, dashboard, entitlements, experiments, finance, integrations, ledger, metering, onboarding, quotes, settings, tax, tokens and warehouse. An agent key can be limited to some of them when you create it, and a client can narrow a connection further with an X-Meterbox-Toolsets: catalog,customers header. It can never widen what the key allows.

Example prompts

Limits

Activity, privacy and data

Disconnect

Support

Questions or problems: contact us. To report a security issue, see the vulnerability disclosure policy.