Connect Billsby to Claude: Automate Invoices & Subscriptions via MCP

You want to connect Billsby to Claude so your AI agents can read customer subscriptions, issue refunds, and modify billing plans directly from a chat interface. If your team uses ChatGPT, check out our guide on connecting Billsby to ChatGPT, or if you are building autonomous workflows, read about connecting Billsby to AI Agents. Here is exactly how to do it using a Model Context Protocol (MCP) server.

Giving a Large Language Model (LLM) read and write access to your billing and subscription infrastructure is an engineering challenge. You either spend weeks building, hosting, and maintaining a custom MCP server, or you use a managed infrastructure layer that handles the boilerplate for you. This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for Billsby, connect it natively to Claude Desktop, and execute complex billing workflows using natural language.

The Engineering Reality of Custom Billsby Connectors

A custom MCP server is a self-hosted integration layer that translates an LLM's tool calls into REST API requests. While Anthropic's open standard provides a predictable way for models to discover tools, implementing it against vendor APIs is painful.

Billsby's API has specific quirks that make it particularly tricky to expose directly to an LLM without a translation layer.

The companyDomain Requirement Almost every endpoint in the Billsby API requires the companyDomain as a path or query parameter. If you build a custom server, you must explicitly inject this into every LLM prompt or hardcode it into your server logic.

Customer vs. Subscription Hierarchy In Billsby, a customer entity is distinct from a subscription entity, yet many operations require both a customerUniqueId and a subscriptionUniqueId. LLMs routinely hallucinate or mix up these IDs when trying to string together multi-step billing changes.

Complex Pagination Schemes Billsby uses page and pageSize parameters for list endpoints. When Claude asks for "all invoices for the last year", it does not intuitively know how to paginate through 50 pages of results. Truto normalizes this by injecting clear cursor and limit instructions directly into the tool's query schema, instructing the LLM exactly how to traverse the dataset.

How to Generate a Managed MCP Server for Billsby

Instead of building this translation layer from scratch, you can use Truto to dynamically generate an MCP server URL. Truto automatically derives tool definitions from the Billsby integration's resource schemas and handles the underlying authentication and pagination.

You can generate this server in two ways.

Method 1: Via the Truto UI

For internal teams and quick testing, the dashboard is the fastest path.

1. Navigate to the integrated account page for your connected Billsby instance.
2. Click the MCP Servers tab.
3. Click Create MCP Server.
4. Select your desired configuration (name, allowed methods, tags, and expiration).
5. Copy the generated MCP server URL.

Method 2: Via the API

For production use cases where you are provisioning AI agents programmatically, hit the Truto API.

POST /integrated-account/:id/mcp
{
  "name": "Claude Billing Assistant",
  "config": {
    "methods": ["read", "write"]
  }
}

The API returns a ready-to-use JSON-RPC 2.0 endpoint URL containing a cryptographic token.

Connecting the MCP Server to Claude

Once you have the URL, connecting it to Claude takes seconds.

Method A: Via the Claude UI

If you are using Claude for Enterprise or Claude Desktop with UI configuration enabled:

1. Open Claude and navigate to Settings -> Integrations.
2. Click Add MCP Server.
3. Paste your Truto MCP URL and click Add.

Method B: Via Manual Config File

For local Claude Desktop deployments, you can configure the server using the claude_desktop_config.json file. Truto provides an SSE (Server-Sent Events) endpoint.

{
  "mcpServers": {
    "billsby-truto": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "https://api.truto.one/mcp/YOUR_TRUTO_TOKEN"
      ]
    }
  }
}

Restart Claude Desktop. The tools will immediately populate in your interface.

How Truto Maps Billsby to MCP Tools

When Claude calls the tools/list endpoint, Truto does not serve a static, hardcoded list of functions. Instead, it dynamically generates tool definitions by iterating over the Billsby integration's resources and documentation records.

For every endpoint, Truto compiles the YAML documentation into JSON Schema format. If an endpoint requires pagination, Truto automatically injects limit and next_cursor properties into the query schema, complete with explicit instructions telling the LLM to pass cursor values back exactly as received. This documentation-driven approach acts as a strict quality gate - if an endpoint lacks proper schema definitions, it is intentionally excluded from the MCP server.

sequenceDiagram
    participant User as Claude User
    participant Claude as Claude Desktop
    participant Truto as Truto MCP Server
    participant Billsby as Billsby API

    User->>Claude: "Refund invoice INV-10492"
    Claude->>Truto: tools/call (billsby_invoices_refund_invoice)
    Note over Truto: Validates MCP token<br>Applies tag/method filters
    Truto->>Billsby: POST /api/v1/companyDomain/invoices/INV-10492/refund
    Billsby-->>Truto: 200 OK
    Truto-->>Claude: Tool result (Success)
    Claude-->>User: "The invoice has been refunded."

Security and Access Control

Giving an LLM access to your billing system is inherently risky. Truto provides strict access controls at the MCP token level to limit the blast radius.

• Method filtering: Restrict the MCP server to read-only operations using config.methods: ["read"]. This prevents Claude from accidentally refunding invoices or deleting subscriptions during exploration.
• Tag filtering: Restrict access to specific resource types using config.tags: ["invoices"].
• Token auth: Set require_api_token_auth: true for enterprise environments. This forces the MCP client to provide a valid Truto API token in the Authorization header, adding a second layer of security beyond the URL token.
• Ephemeral access: Use the expires_at field to generate temporary credentials for contractors or short-lived agent sessions. The platform automatically schedules work to revoke access the moment the token expires.

Billsby Hero Tools

Truto automatically exposes Billsby's API endpoints as structured tools. Here are the most critical tools for billing automation.

billsby_invoices_refund_invoice

• Description: Refund a specific invoice for a customer in Billsby. Requires company_domain, customer_unique_id, and invoiceNumber.
• Example Prompt: "Refund invoice INV-10492 for customer CUST-8819. They requested a cancellation within the 14-day window."

billsby_invoices_reattempt_invoice_payment

• Description: Reattempt a failed invoice payment using invoiceNumber and companyDomain.
• Example Prompt: "The customer updated their card on file. Please reattempt the payment for invoice INV-10493."

billsby_subscriptions_change_plan

• Description: Change the plan of a subscription in Billsby. Requires company_domain, id (subscription ID), planId, and cycleId.
• Example Prompt: "Upgrade subscription SUB-9921 to the Enterprise plan (planId: 44, cycleId: 2)."

billsby_invoices_invoice_written_off

• Description: Mark an invoice as written off in Billsby. Useful for cleaning up bad debt.
• Example Prompt: "Mark invoice INV-10021 as written off. The account has been sent to collections."

create_a_billsby_one_time_charge

• Description: Create a one-time charge for a specific customer.
• Example Prompt: "Apply a one-time setup fee of $500 to customer CUST-8819."

list_all_billsby_event_logs

• Description: Get event logs for a specific subscription to audit changes and billing history.
• Example Prompt: "Pull the event logs for subscription SUB-9921 over the last 30 days to see when their plan was downgraded."

Complete Billsby Tool Inventory

Here is the complete inventory of additional Billsby tools available. For full schema details, visit the Billsby integration page.

• list_all_billsby_payments: Get payment logs for a specific customer payment in Billsby.
• billsby_company_credit_notes_reattempt_credit_note_payment: Reattempt a failed credit note payment.
• billsby_invoices_invoice_paid_offline: Mark an invoice as paid offline.
• list_all_billsby_customer_invoices: Get invoices for a specific customer.
• get_single_billsby_subscription_feature_tag_by_id: Get feature tags split by plan and custom tags.
• billsby_subscriptions_update_next_renewal_date: Update next renewal date for a subscription.
• list_all_billsby_subscription_feature_tags: Get feature tags for a subscription.
• delete_a_billsby_subscription_feature_tag_by_id: Delete a custom feature tag by tagname.
• list_all_billsby_company_credit_notes: Get a list of all company credit notes.
• list_all_billsby_customer_credit_notes: Get customer credit notes.
• update_a_billsby_plan_order_by_id: Update the order of plans for a product.
• create_a_billsby_subscription_feature_tag: Add feature tags to subscriptions.
• update_a_billsby_payment_card_token_by_id: Update payment card token for a customer.
• get_single_billsby_payment_details_request_by_id: Get a request to update payment details.
• list_all_billsby_customer_feature_tags: Get all feature tags associated with a customer.
• update_a_billsby_clear_customer_datum_by_id: Clear personal data for a customer.
• get_single_billsby_subscription_shipping_address_by_id: Get shipping address for a subscription.
• update_a_billsby_subscription_shipping_address_by_id: Update subscription shipping address.
• update_a_billsby_counter_value_by_id: Update counter value for a subscription.
• get_single_billsby_counter_value_by_id: Get current usage and last updated timestamp of a counter.
• delete_a_billsby_customer_subscription_by_id: Cancel a subscription.
• list_all_billsby_customer_subscriptions: Get a list of subscriptions for a customer.
• create_a_billsby_subscription: Create a new subscription and customer.
• update_a_billsby_customer_subscription_by_id: Add a subscription to an existing customer.
• get_single_billsby_subscription_by_id: Get subscription details by id.
• billsby_invoices_customer_invoices: Get invoices for a specific customer.
• list_all_billsby_subscriptions: List subscriptions for companyDomain.
• create_a_billsby_customer: Create a customer without a subscription.
• update_a_billsby_customer_by_id: Update customer details.
• create_a_billsby_custom_field: Create a new custom field.
• update_a_billsby_custom_field_by_id: Update an existing custom field.
• list_all_billsby_custom_fields: Get a list of all custom fields configured.
• create_a_billsby_cycle: Create a cycle for a specific plan.
• list_all_billsby_plans: Get a list of plans for a product.
• update_a_billsby_plan_by_id: Update a plan and cycle.
• create_a_billsby_plan: Create a new plan for a specific product.
• list_all_billsby_products: List products for companyDomain.
• create_a_billsby_product: Create a new product.
• get_single_billsby_product_by_id: Get details of a specific product.
• update_a_billsby_product_by_id: Update product.
• list_all_billsby_subscription_add_ons: Get add-ons for a specific subscription.
• list_all_billsby_subscription_allowances: Get allowances for a specific subscription.
• get_single_billsby_allowance_by_id: Get allowance details by allowanceId.
• get_single_billsby_add_on_by_id: Get details of a specific add-on.
• list_all_billsby_allowances: Get a list of all allowances.
• list_all_billsby_add_ons: Get a list of all add-ons.
• get_single_billsby_customer_by_id: Get customer details by id.
• delete_a_billsby_customer_by_id: Delete a customer by id.
• list_all_billsby_invoices: Get a list of your company's invoices.
• get_single_billsby_invoice_by_id: Get invoice details by invoiceNumber.
• list_all_billsby_customers: List customers by companyDomain.

Workflows in Action

To understand how this looks in practice, let us trace three concrete billing operations executed entirely through Claude.

Scenario 1: Handling a churn risk and issuing a refund

A support agent receives an angry email from a customer who forgot to cancel their subscription before the renewal date. They ask Claude to handle the cancellation and refund.

"Customer CUST-4029 wants to cancel their subscription SUB-1192 and get a refund for their latest invoice INV-9920."

Execution flow:

1. Claude calls delete_a_billsby_customer_subscription_by_id passing the subscriptionUniqueId and customerUniqueId to immediately halt future billing.
2. Claude calls billsby_invoices_refund_invoice passing the invoiceNumber to return the funds to the customer's card.
3. Claude returns a summary to the support agent confirming the subscription is cancelled and the refund has been initiated.

Scenario 2: Upgrading a plan and charging a setup fee

A sales rep just closed an upsell. The customer is moving to the Enterprise tier, which requires a mandatory one-time implementation fee.

"Upgrade customer CUST-5510's subscription SUB-8822 to the Enterprise plan (planId: 44, cycleId: 2) and charge them a $1,000 one-time implementation fee."

Execution flow:

1. Claude calls billsby_subscriptions_change_plan with the new planId and cycleId to update the recurring billing logic.
2. Claude calls create_a_billsby_one_time_charge for CUST-5510 with the $1,000 amount and a description of "Enterprise Implementation Fee".
3. Claude confirms the plan upgrade is active and the one-time charge has been successfully generated.

Scenario 3: Dunning and payment reattempts

A customer replies to an automated dunning email saying they have updated their expired credit card.

"Customer CUST-3312 updated their card. Please reattempt payment on their failed invoice INV-8811."

Execution flow:

1. Claude calls billsby_invoices_reattempt_invoice_payment using the invoiceNumber.
2. If the payment succeeds, Claude returns a success message. If the upstream API returns an HTTP 429 rate limit error or a card decline, Truto passes that error directly back to Claude. Claude reads the error payload and informs the user that the new card was also declined.

Next Steps

Building a custom MCP server for Billsby forces your engineering team to manage authentication state, pagination logic, and massive JSON schemas. Using a managed platform offloads that entire lifecycle.