Lago Agent Toolkit

August 25, 2026 · View on GitHub

MCP server and agent tools for Lago. Lets AI agents read and write billing data in Lago — invoices, events, customers, payments, credit notes, coupons — via the Model Context Protocol.

Works with Claude Desktop today.

What's inside

An MCP (Model Context Protocol) server written in Rust, distributed as a Docker image. It bridges AI agents and Lago's billing API.

Features:

  • Full access to Lago's billing primitives as 40 MCP tools
  • Type-safe Rust implementation
  • Multi-architecture Docker image (AMD64 & ARM64)
  • Pagination support for large datasets
  • Filter invoices, customers, payments, events with rich query parameters

The Managed Agents context

Anthropic launched Claude Managed Agents on April 8, 2026. As of that release, two observable constraints in Anthropic's Admin API:

  • The Usage Report API's group_by parameter accepts 7 values: api_key_id, workspace_id, model, service_tier, context_window, inference_geo, speed. agent_id and session_id are not among them.
  • Session creation accepts agent, environment_id, and vault_ids. No customer_id, metadata, or external_id.

For operators deploying Managed Agents to their own customers and needing per-session or per-customer attribution to bill those customers, the attribution data isn't exposed by Anthropic's API. The Lago Agent Toolkit surfaces Lago's billing primitives via MCP so that layer can be built on Lago rather than hand-rolled.

Quick start (Claude Desktop)

  1. Install Docker Desktop
  2. Open Claude Desktop → Settings → Developer → Edit Config
  3. Add the Lago MCP server:
{
  "mcpServers": {
    "lago": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--name", "lago-mcp-server",
        "-e", "LAGO_API_KEY=your_lago_api_key",
        "-e", "LAGO_API_URL=https://api.getlago.com/api/v1",
        "-e", "LAGO_AGENT_API_URL=https://agent.getlago.com",
        "getlago/lago-mcp-server:latest"
      ]
    }
  }
}
  1. Replace your_lago_api_key with your actual Lago API key (find it in your Lago dashboard under API settings).
  2. Restart Claude Desktop. The agent can now call Lago.

For self-hosted Lago, replace LAGO_API_URL with your instance URL.

Analytics tool: ask_lago_analytics additionally requires LAGO_AGENT_API_URL (the URL of the Lago analytics agent). If it's not set, the other tools work normally and only the analytics tool returns a configuration error. Note: this tool forwards your X-LAGO-API-KEY to the analytics agent service (a first-party Lago service that re-validates the key and applies the same per-organization row-level security as the Rails API). It is the one tool that does not route through the Lago REST API — see the PR description / docs/ for the architecture rationale.

Example prompts

  • "Show me all pending invoices from last month" → list_invoices
  • "Find all failed payment invoices" → list_invoices
  • "Give me the total amount of overdue invoices for March 2025" → list_invoices + agent aggregation
  • "Preview an invoice for customer X with 500 additional API-call events" → preview_invoice
  • "Retry payment on invoice INV-123" → retry_invoice_payment
  • "What was our MRR for December 2025, broken down by plan?" → ask_lago_analytics
  • "List the top 10 customers by usage volume in Q1 2026." → ask_lago_analytics
  • "How many invoices went overdue last month?" then "Break that down by customer country." → ask_lago_analytics (the second call reuses the returned session_id)

Available Tools

Analytics

  • ask_lago_analytics: Ask a natural-language question about your billing and usage data (revenue, MRR, invoices, customers, subscriptions, usage volumes). The analytics agent generates a read-only SQL query, runs it, and returns the SQL, a plain-language explanation, and a results table. The response includes a session_id — pass it back on a follow-up call to refine the same result (filter, aggregate, sort) using the agent's cached rows.

Invoices

  • find_invoice_by_number: Find an invoice by its number (e.g., "RAF-8142-202601-312") and get its Lago ID
  • get_invoice: Retrieve a specific invoice by Lago ID
  • delete_invoice: Delete a draft invoice by Lago ID after confirming the action; this cannot be undone
  • list_invoices: Search and filter invoices with advanced criteria
  • list_customer_invoices: List all invoices for a specific customer
  • create_invoice: Create a one-off invoice with add-on fees, each optionally carrying a service period (from_datetime / to_datetime)
  • update_invoice: Update an invoice's payment status or metadata
  • preview_invoice: Preview an invoice before creating it
  • refresh_invoice: Refresh a draft invoice to recalculate charges
  • download_invoice: Download an invoice PDF
  • retry_invoice: Retry generation of a failed invoice
  • retry_invoice_payment: Retry payment collection for an invoice
  • void_invoice: Void a finalized invoice to prevent further modifications or payments

Fees

  • list_fees: List fees with filtering by fee type, billable metric code, customer, subscription, currency, payment status, and date range. Useful for custom revenue reporting and MRR calculations that need to include selected usage charges (e.g., seats, storage) alongside subscription fees.
  • get_fee: Retrieve a specific fee by its Lago ID

Customers

  • get_customer: Retrieve a customer by external ID
  • list_customers: List customers with optional filtering
  • create_customer: Create or update a customer

Billable Metrics

  • get_billable_metric: Retrieve a billable metric by code
  • list_billable_metrics: List billable metrics with optional filtering
  • create_billable_metric: Create a new billable metric

Coupons

  • get_coupon: Retrieve a coupon by code
  • list_coupons: List all coupons
  • create_coupon: Create a new coupon
  • update_coupon: Update an existing coupon
  • delete_coupon: Delete a coupon

Applied Coupons

  • list_applied_coupons: List applied coupons with optional filtering
  • apply_coupon: Apply a coupon to a customer

Events

  • get_event: Retrieve a usage event by transaction ID
  • create_event: Send a usage event to Lago
  • list_events: List usage events with optional filtering by subscription, code, and timestamp range

Credit Notes

  • get_credit_note: Retrieve a specific credit note by Lago ID
  • list_credit_notes: List credit notes with optional filtering
  • create_credit_note: Create a credit note for an invoice
  • update_credit_note: Update a credit note's refund status

Payments

  • get_payment: Retrieve a specific payment by Lago ID
  • list_payments: List all payments with optional filtering by customer and invoice
  • list_customer_payments: List all payments for a specific customer
  • create_payment: Create a manual payment for an invoice

Activity Logs

  • get_activity_log: Retrieve a specific activity log
  • list_activity_logs: List activity logs with optional filtering

API Logs

  • get_api_log: Retrieve a specific API log
  • list_api_logs: List API logs with optional filtering

Contributing

Issues and PRs welcome.

About Lago

Lago is the open-source billing platform for AI-native companies. Real-time metering, programmatic invoicing, self-hostable. Used in production by PayPal, Mistral AI, Groq, Synthesia, and Laravel. AI-infrastructure companies such as CoreWeave also run Lago.

License

MIT License - see LICENSE for details.