@meterbox/mcp

The Model Context Protocol server for Meterbox. Every Meterbox deployment serves it at <your Meterbox host>/mcp/sandbox and /mcp/production; this package is the same code, plus a meterbox-mcp command that bridges stdio-only MCP clients to that endpoint.

Connect

Create an agent key in Meterbox under Settings > API keys. Agent keys work only with MCP, belong to one environment (mb_agent_sandbox_... or mb_agent_production_...), and are read-only unless you choose otherwise.

Keep the key in an environment variable rather than pasting it into config files:

export METERBOX_AGENT_KEY=mb_agent_sandbox_...

Claude Code

claude mcp add --transport http meterbox-sandbox https://meterbox.ai/mcp/sandbox \
  --header "Authorization: Bearer ${METERBOX_AGENT_KEY}"

Any client that runs a local command (stdio)

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

The key's prefix picks the environment. Add "--toolsets", "catalog,customers" to args to expose only some toolsets; this can narrow what the key allows but never widen it. On a self-hosted deployment, use your own host instead of https://meterbox.ai.

Requires Node.js 20 or later.

Tools

Seven tools cover the whole /v1 API instead of one tool per endpoint:

| Tool | What it does | | ----------------------------- | ---------------------------------------------------------- | | meterbox_whoami | Environment, access level, toolsets and available tools | | meterbox_search_operations | Find operations by keyword, toolset or tier | | meterbox_describe_operation | One operation's path, query and body inputs | | meterbox_read | Run a read operation (GETs, previews, quotes, simulations) | | meterbox_create | Run an operation that only adds records | | meterbox_update | Run an operation that changes records or settings | | meterbox_destructive | Run an irreversible or money-moving operation |

Which tools a connection gets depends on its key:

• Read-only keys get the first four.
• Read-write sandbox keys also get meterbox_create and meterbox_update, and meterbox_destructive when the sandbox's billing provider isn't connected in live mode.
• Production keys are read-only over MCP. Use the dashboard for production changes.

Each execute tool only runs operations of its own tier, so a tool marked read-only can never make a change. Operations that return or set credentials, configure outbound destinations (webhooks, emails, data sinks), create checkout or portal sessions, or export data in bulk are not available over MCP at all, and secret-shaped values are removed from every result.

Hosting it yourself

Meterbox deployments already run this server. To embed it elsewhere:

const { buildCatalog, createServerFactory, createHttpHandler } = require("@meterbox/mcp");

const catalog = buildCatalog(openApiSpec);
const factory = createServerFactory({
  catalog,
  dispatch: async (op, { pathParams, query, body }, { principal }) => {
    // call the API for this principal; resolve { status, body }
  },
  apiReferenceUrl: "https://your-host/docs",
});
const mcp = createHttpHandler({ factory });

app.post("/mcp/:environment", authenticate, (req, res) =>
  mcp.handle(req, res, { principal: req.principal }),
);

The principal is { environment, access, toolsets, destructive_allowed, key_id }. Authentication, rate limiting and audit hooks (hooks.beforeCall, hooks.afterCall, hooks.onDenied) are the host's job.