Agent Billy MCP Server

Local MCP proxy that gives AI assistants (Claude, Cursor, Copilot) secure, role-based access to your Stripe billing through your Billy container API.

Quick Start

npx agent-billy --api-url https://yourorg.agentbilly.ai --token YOUR_API_KEY

Or use environment variables:

export BILLY_API_URL=https://yourorg.agentbilly.ai
export BILLY_TOKEN=billy_your-api-key
npx agent-billy

MCP Configuration

Claude Desktop

Add to your claude_desktop_config.json:

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

Config file locations:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Claude Code

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

Cursor

Go to Settings > MCP Servers > Add new MCP server and enter:

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

VS Code (GitHub Copilot)

Add to your settings.json:

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

Authentication

Generate an API key from your Billy dashboard:

1. Log in at https://yourorg.agentbilly.ai
2. Go to Settings > API Keys
3. Click Generate Key and choose a role
4. Copy the key and use it as BILLY_TOKEN

API keys inherit the role you assign when creating them. A Billing Clerk key can only perform Billing Clerk actions. Keys can be revoked at any time from Settings.

Available Tools

Read Tools

| Tool | Description | |------|-------------| | billy_list_charges | List recent charges. Filter by status (succeeded, failed, pending). | | billy_get_charge | Get details for a specific charge by Stripe charge ID. | | billy_list_customers | List customers with pagination. | | billy_get_customer | Get details for a specific customer by Stripe customer ID. | | billy_list_subscriptions | List subscriptions. Filter by status (active, past_due, canceled, trialing). | | billy_list_invoices | List invoices. Filter by status (draft, open, paid, void, uncollectible). | | billy_list_refunds | List all refunds that have been issued. | | billy_get_stats | Dashboard snapshot: MTD revenue, success rate, active subs, failed charges. | | billy_search | Search across customers, charges, subscriptions, and invoices by keyword. |

Write Tools

| Tool | Description | |------|-------------| | billy_create_refund | Issue a full or partial refund for a charge. | | billy_create_customer | Create a new Stripe customer. | | billy_update_customer | Update a customer's email, name, description, or metadata. | | billy_cancel_subscription | Cancel a subscription (at period end or immediately). | | billy_reactivate_subscription | Reactivate a canceled subscription that hasn't fully expired. | | billy_send_invoice | Send an invoice to the customer via email. | | billy_void_invoice | Void an invoice so it can no longer be paid. | | billy_create_coupon | Create a discount coupon (percentage or fixed amount). | | billy_delete_coupon | Delete a coupon so it can't be applied to new customers. |

Role-Based Access

All permissions are enforced server-side. The token inherits the role of the user who created it.

| Role | Read | Refunds | Manage Subs | Invoices | Customers | Coupons | |------|------|---------|-------------|----------|-----------|---------| | Owner | All | Unlimited | Full | Full | Full | Full | | Billing Manager | All | Up to $5,000 | Full | Full | Full | Full | | Billing Clerk | All | Up to $100 | View only | View only | Update only | No | | Read Only | All | No | No | No | No | No |

Spending Limits

Refund limits are enforced per transaction, per role:

• Owner: No limit
• Billing Manager: $5,000 per refund
• Billing Clerk: $100 per refund
• Read Only: Cannot issue refunds

Attempting to exceed your limit returns a permission error. The action is logged in the audit trail.

CLI Options

agent-billy --api-url <url> --token <jwt>

Options:
  --api-url   Billy container API URL (or BILLY_API_URL env var)
  --token     JWT auth token (or BILLY_TOKEN env var)
  --api-key   API key, alternative to token (or BILLY_API_KEY env var)
  --help, -h  Show help

Links

• Website: agentbilly.ai
• Docs: agentbilly.ai/docs
• npm: npmjs.com/package/agent-billy
• Support: [email protected]