Agent Billy Docs

Agent Billy has four setup steps. Each one takes about a minute.

Billy uses a Restricted API Key — not your full secret key. Restricted keys give Billy only the permissions it needs, and nothing else.

How to create a Restricted Key

1. 1Open the Stripe Dashboard → Developers → API Keys and click Create restricted key.
2. 2Give it a name like Agent Billy.
3. 3Under Permissions, enable the following:
4. 4Copy the key — it starts with rk_live_. Paste it into the Billy onboarding wizard.

How Billy stores your key

When you paste your key, it is immediately encrypted and stored in Azure Key Vault. The plaintext key is never written to a database, log file, or browser. Your team members and Billy's dashboard never receive the key — only Billy's server-side API calls use it.

Set up Stripe Webhooks

Webhooks enable real-time sync — when a charge succeeds, a subscription changes, or a refund is issued, your Billy dashboard updates instantly instead of waiting for the next manual sync.

1. 1Go to Stripe Dashboard → Developers → Webhooks and click Add endpoint.
2. 2Set the endpoint URL to your workspace URL followed by /webhooks/stripe. For example: https://your-org.agentbilly.ai/webhooks/stripe
3. 3Under Select events, click Select all events or choose at minimum:
4. 4Click Add endpoint to save.
5. 5Click into your new endpoint and find the Signing secret — it starts with whsec_. Copy it.
6. 6In your Billy dashboard, go to Settings → Webhook Configuration and paste the signing secret.

Invite team members from the onboarding wizard or later from Settings → Team in your dashboard.

1. 1Go to Settings → Team → Invite Member.
2. 2Enter the team member's work email address.
3. 3Select their role (see Roles & Permissions below).
4. 4Click Send Invite. They'll receive a magic-link email valid for 48 hours.
5. 5Once they accept, they appear in your team list and can log into your Billy dashboard immediately.

Billy has four built-in roles. Each role is a strict subset of the one above it — there's no permission creep.

Connect Agent Billy to your AI tool of choice. Billy runs as an MCP server over stdio transport, so it works with any MCP-compatible client.

Prerequisites

1. 1Your API URL is your Billy workspace URL, e.g. https://yourorg.agentbilly.ai.
2. 2Generate an API Key in your Billy dashboard under Settings > API Keys. Click Generate Key, choose a role, and copy the key. Keys inherit the role you assign.

{
  "mcpServers": {
    "agent-billy": {
      "command": "npx",
      "args": ["-y", "agent-billy"],
      "env": {
        "BILLY_API_URL": "https://yourorg.agentbilly.ai",
        "BILLY_TOKEN": "billy_your-api-key"
      }
    }
  }
}

claude mcp add agent-billy \
  -e BILLY_API_URL=https://yourorg.agentbilly.ai \
  -e BILLY_TOKEN=billy_your-api-key \
  -- npx -y agent-billy

{
  "command": "npx",
  "args": ["-y", "agent-billy"],
  "env": {
    "BILLY_API_URL": "https://yourorg.agentbilly.ai",
    "BILLY_TOKEN": "billy_your-api-key"
  }
}

{
  "mcp": {
    "servers": {
      "agent-billy": {
        "command": "npx",
        "args": ["-y", "agent-billy"],
        "env": {
          "BILLY_API_URL": "https://yourorg.agentbilly.ai",
          "BILLY_TOKEN": "billy_your-api-key"
        }
      }
    }
  }
}

Billy exposes 19 tools through MCP. Your AI assistant can call any of these — permissions are enforced server-side based on your role.

Read Tools

Write Tools

Refund limits are enforced per transaction, per role. These limits apply whether the action is performed from the dashboard or through the AI agent — they are checked server-side and cannot be bypassed.

Billy is also an MCP server. Connect it to Claude Desktop, Claude Code, Cursor, or any MCP-compatible tool to manage billing with plain English.

Setup with Claude Desktop

1. 1Install Billy's CLI: run npx agent-billy in your terminal. It will open a browser to authenticate your account.
2. 2Once authenticated, add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "agent-billy": {
      "command": "npx",
      "args": ["agent-billy", "--mcp"]
    }
  }
}

Restart Claude Desktop. Billy will appear in the MCP tools list.

Example conversations