Agent Billy as an MCP Server: Billing in Plain English

What Is MCP?

The Model Context Protocol is an open standard from Anthropic that lets AI assistants connect to external tools and data sources. Instead of the AI guessing or hallucinating about your data, it can query real systems and take real actions — with your permission.

Think of it as a USB port for AI. Any MCP-compatible client (Claude Desktop, Cursor, VS Code with Copilot) can plug into any MCP server and use its tools.

Why Billing Needs This

Imagine you're a support lead and you get a message: "Customer Acme Corp says they were double-charged last month." Today, you'd:

1. Open the Stripe dashboard (or Agent Billy's dashboard)
2. Search for Acme Corp
3. Find their customer record
4. Look through recent charges
5. Identify the duplicate
6. Issue a refund
7. Send a confirmation

With MCP, you can say to Claude: "Check if Acme Corp was double-charged last month and refund the duplicate if so."

Claude connects to Agent Billy's MCP server, queries your synced billing data, identifies the duplicate charge, and — if your role permits — issues the refund. All in one natural language request.

How We Built It

Agent Billy's MCP server exposes a set of tools that map to billing operations:

// Available MCP tools
billy_search_customers    // Find customers by name, email, or ID
billy_get_customer        // Get full customer details
billy_list_subscriptions  // List subscriptions with filters
billy_list_invoices       // List invoices with filters
billy_list_charges        // List charges with filters
billy_get_mrr             // Get current MRR and growth metrics
billy_issue_refund        // Refund a charge (Manager+ only)
billy_cancel_subscription // Cancel a subscription (Manager+ only)

Each tool respects the same RBAC system as the dashboard. If you're connected with a Viewer role token, billy_issue_refund will return a permission error — not execute the refund.

The Local Proxy

MCP servers typically run locally. Our agent-billy npm package (installable via npx agent-billy) runs a lightweight proxy on your machine that:

1. Authenticates with your Agent Billy account
2. Establishes a secure connection to your container
3. Exposes MCP tools to your AI client
4. Enforces role-based permissions on every call

# Install and connect
npx agent-billy login
npx agent-billy mcp start

Your AI client connects to localhost, the proxy forwards requests to your container, and responses flow back. Your Stripe data never touches the AI provider's servers — it goes from your container to your machine to your local AI client.

Real-World Usage

Here are the kinds of queries we've seen in testing:

• "What's our MRR this month vs last month?"
• "Show me all customers whose subscriptions are past due."
• "Find the charge for invoice INV-2026-0042 and tell me if it succeeded."
• "Cancel John Smith's subscription at period end and draft a confirmation email."

The power isn't in any single query — it's in chaining them together conversationally, with an AI that understands context and can ask clarifying questions.

Security Considerations

We were deliberate about security:

• No secret keys in AI context. The MCP proxy handles auth. The AI never sees API keys.
• Role enforcement. Every tool call checks permissions server-side.
• Confirmation prompts. Destructive actions (refunds, cancellations) require explicit user confirmation in the AI client.
• Audit logging. Every MCP action is logged with the same detail as dashboard actions, tagged as source: mcp.