VayuDocumentationIntegrationsAPI ReferenceChange Log
SupportGet started now
GuidesAI

Vayu MCP Server

Connect AI assistants like Claude and Cursor to your Vayu workspace through the Vayu MCP server.

Vayu MCP Overview

Vayu MCP lets AI assistants connect directly to your Vayu workspace using the Model Context Protocol (MCP).

With it, your team can ask natural-language questions about customers, contracts, invoices, plans, catalog products, meters, credits, and custom field definitions, using live data from Vayu.

It is built to remove the manual back and forth between your billing system and your AI tools. Instead of exporting reports or copying numbers into prompts, your team can query billing and revenue data directly in plain English.

This is designed for customer-facing and internal operations use cases such as:

  • Looking up a customer or contract
  • Reviewing invoice status and payment state
  • Exploring billing plans and catalog products
  • Understanding meter configuration
  • Inspecting credit ledger activity
  • Powering AI copilots and internal ops workflows

What You Can Do With Vayu MCP

Today, Vayu MCP is focused on secure, read-oriented access to billing and revenue data in your Vayu account.

You can use it for high-value finance and billing questions including revenue recognition by period (MRR, ARR, NRR, and GRR), deferred revenue, waterfall analysis, contract/renewal lookups, overdue AR, invoice status, and cross-entity search.

Available tool groups include:

  • Customers
    • Find customers by name, external ID, or integration ID
    • Fetch full customer details, including payment terms
  • Contracts
    • Retrieve a contract by Vayu ID or supported integration ID
    • List contracts, optionally filtered by customer and other supported fields
  • Invoices
    • List invoices, optionally filtered by customer, an exact invoice number, and other supported fields
    • Fetch full invoice details, including line items and totals
    • Check invoice payment status
    • Include deleted invoices in a list
  • Record history
    • See who did what to a contract or invoice, and when
  • Catalog products
    • List catalog products
    • Fetch a specific catalog product
  • Plans
    • List plans
    • Fetch a specific plan
  • Meters
    • List meters
    • Fetch a specific meter
  • Custom fields
    • List custom field definitions for supported entities
  • Credits
    • List credit ledger entries, optionally filtered by customer
  • Reports
    • Usage report
    • Commitment vs. usage
  • Recurring revenue
    • List MRR and ARR per contract and product, month by month, including future months

Tool names are prefixed with vayu_ in MCP clients. List endpoints support pagination, and list results follow the server's supported sorting semantics where available.

What You Get Back

vayu_find_customers, vayu_get_customer, vayu_list_contracts, vayu_get_contract, vayu_list_invoices, and vayu_get_invoice each return an appUrl. It is a direct link to that record in the app at app.withvayu.com: the customer page, the contract page, or the invoice page.

appUrl is not returned by vayu_get_invoice_payment_status, the usage report, the commitment-vs-usage report, or credits.

Readable status labels

Raw status values are kept, and a label field is added next to each one so it matches the status shown in the app.

  • statusLabel is on customers, contracts, the usage report, and commitment-vs-usage. Commitment-vs-usage also includes contractStatusLabel.
  • billingStatusLabel is on vayu_list_invoices, vayu_get_invoice, and vayu_get_invoice_payment_status.
  • Aggregates include keyLabel and billingStatusLabel.
Raw valueLabel
Customer SuspendedChurned
Contract InReviewPending review
Invoice NoneOpen
Invoice RejectedCancelled
Invoice PendingPaymentPending payment
Invoice on a trial contractTrial

Invoice number filter

vayu_list_invoices accepts an exact invoiceNumber filter.

Deleted invoices

vayu_list_invoices hides deleted invoices by default. Set includeDeleted: true to include them. A deleted invoice has deletedAt, the time it was deleted, and its original invoiceNumber, so invoiceNumber with includeDeleted: true also finds a deleted invoice by its old number.

Customer payment terms

vayu_get_customer returns paymentTerms:

  • dueDays: the number of days after the issue date that an invoice is due. 0 means due on receipt.
  • endOfMonth: true when invoices are due on the last day of the month they are issued in. dueDays is then null.
  • setOn: where the terms come from: customer, accountDefault when the customer has none, or vayuDefault when neither the customer nor the account sets terms.

Invoices that are not yet approved follow these terms. An approved invoice keeps the terms it was approved with. Read its due date from vayu_get_invoice.

Record history

vayu_get_record_history returns the history of one contract or invoice, newest first. Pass recordType (contract or invoice) and the record's Vayu id, and page with limit and cursor.

Each row shows the event, when it was recorded, who did it (a user or an automated system), the fields that changed, and invoice facts such as the payment date, amount, source, or email recipients. Actions by Vayu employees show as Vayu team. The tool also works for a deleted invoice.

History starts when Vayu began recording each kind of event: September 23, 2026 for contracts, and later for invoice events, invoice deletes, and contract deactivations and reactivations. An empty history doesn't prove that nothing happened. For an older invoice delete, use vayu_list_invoices with includeDeleted: true and read deletedAt.

Recurring revenue by contract and product

vayu_list_recurring_revenue lists monthly MRR and ARR for each contract, with every product nested under its contract. Use it for a breakdown by customer, contract, and product, or for future months, such as ARR through the end of a contract. The figures are recurring (subscription) revenue, not invoiced revenue, and all amounts are in USD.

ParameterDescription
customerIdOptional. Limits the results to one customer.
contractIdOptional. Limits the results to one contract. When you pass both, the contract must belong to the customer.
fromMonthOptional. First month, as YYYY-MM, inclusive. Future months are allowed. The default is 11 months before the current month.
toMonthOptional. Last month, as YYYY-MM, inclusive. Future months are allowed. The default is the current month.
limitOptional. Contracts per page, from 1 to 100. The default is 25.
cursorOptional. The nextCursor from the previous call, to get the next page.
includeTotalCountOptional. Set to true to also return totalCount. The default is false.

With no months set, the tool covers the last 12 months, through the current month. A range can span at most 60 months. A longer range returns an error, so split it into several calls.

The response has:

  • months: the months covered, as YYYY-MM, oldest first.
  • contracts: one entry per contract, ordered by customer name, then contract start date. Each has contractId, contractName, customerId, customerName, status, statusLabel, startDate, endDate (null for a contract with no end date), and renewedContractId, the earlier contract this one renews. A renewal is a separate contract.
  • products on each contract: productId, productName, phase (the phase the product was added in, with its name, label, and effectiveDate, or null), and the mrr and arr arrays. Each value belongs to the month at the same position in months. arr is mrr × 12.
  • nextCursor: pass it as cursor to get the next page. It is null on the last page.
  • totalCount: the number of contracts, when includeTotalCount is true. Otherwise null.

A null in mrr or arr means the month isn't projected. Only contracts with no end date have it: they are projected about 12 months ahead, and later months are null. For a contract with an end date, months outside the contract are 0. Contracts that are 0 in every month of the range are left out.

For a single current MRR or ARR figure, or its trend and movement over time, use vayu_get_mrr instead.

Date fields

  • terminatedAt on vayu_get_contract is the date the termination takes effect, not the time someone terminated the contract.
  • paymentInfo.date on vayu_get_invoice_payment_status and transactionDate on vayu_get_invoice are payment dates, not the time the invoice was marked paid.

Supported AI Clients

Vayu MCP works with MCP-compatible clients, including:

  • Claude Desktop
  • Claude Code
  • Cursor
  • claude.ai
  • MCP Inspector
  • Other MCP clients that support remote HTTP servers and OAuth-based authentication

Authentication

Vayu MCP is exposed as an OAuth 2.1 protected resource.

When a compatible MCP client connects to the Vayu MCP endpoint, it discovers the authorization flow automatically through standard protected-resource metadata, including:

  • The WWW-Authenticate response header
  • The /.well-known/oauth-protected-resource metadata document

From there, the client launches the browser-based sign-in flow and obtains access tokens directly from the configured authorization server, currently Descope.

This means there is no manual token copy and paste for supported clients. Users simply connect to the MCP server and complete sign-in in the browser.

Endpoints

Use the endpoint that matches your environment:

  • Staging: https://mcp.staging.withvayu.com/mcp
  • Production: https://mcp.withvayu.com/mcp

Connect Claude Desktop

  1. Open Claude Desktop MCP settings.
  2. Choose Add MCP server.
  3. Paste the Vayu MCP server URL.
  4. Click Connect.
  5. Complete the browser sign-in flow when prompted.

Once connected, Claude Desktop can use the Vayu MCP tools in your conversations.

Example prompt:

Find customers named Acme and show me their overdue invoices.

Connect Claude Code

Use the CLI to register the server:

claude mcp add --transport http vayu https://mcp.withvayu.com/mcp

Then follow the sign-in flow when Claude Code prompts for authentication.

Connect Claude.ai

  1. Open Settings → Connectors.
  2. Choose Add custom connector.
  3. Paste the Vayu MCP server URL: https://mcp.withvayu.com/mcp
  4. Click Connect.
  5. Complete the browser sign-in flow when prompted.

Once connected, enable the connector in the conversation where you want to use Vayu.

Example Questions to Ask

Here are a few good examples:

  • What's our recognized revenue this quarter?
  • Show ARR by customer, contract, and product through December 2028.
  • Show me deferred revenue for the last 6 months.
  • List contracts renewing in the next 90 days.
  • Which invoices are overdue for Acme?
  • Show me the payment status of invoice inv_123.
  • List active contracts for customer cus_123.
  • What plans are active in this workspace?
  • Show me the details for meter mtr_123.
  • Who approved invoice inv_123, and when?
  • What are the payment terms for customer cus_123?
  • What is this customer's current credit balance?
  • Search for all records related to Fordefi.

Security and Scope

Vayu MCP is designed to be safe to use in production workflows.

A few important notes:

  • Access is scoped to the authenticated Vayu account.
  • The MCP server is read-only and authentication is handled through the OAuth protected-resource flow.
  • Tool responses are structured for AI use and optimized for natural-language workflows.
  • Pagination is supported on list operations for larger datasets.
  • Audit logging and rate limiting are built into the MCP service.
  • Input validation is enforced on every request.

Current Limitations

At this stage, Vayu MCP is best suited for retrieval and analysis workflows.

Keep in mind that the current toolset is primarily read-focused and that available data depends on your Vayu account and configuration. Usage is available through the usage report and commitment-vs-usage tools. Contract billing schedules aren't currently exposed. Finally, client support depends on MCP compatibility and OAuth protected-resource support.

Watch Vayu MCP Connect

This video shows the Vayu MCP connection flow.

Need Help?

If you need help enabling Vayu MCP for your workspace, reach out to your Vayu team contact.

On this page