Connect Zoho Billing to Claude: Automate Expenses & Project Billing

If your team needs to connect Zoho Billing to Claude to automate expense tracking, project billing, or subscription lifecycles, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's JSON-RPC tool calls and Zoho Billing's REST APIs. You can either build and maintain this infrastructure yourself, or use a managed integration platform like Truto to dynamically generate a secure, authenticated MCP server URL.

If your team uses ChatGPT, check out our guide on /connect-zoho-billing-to-chatgpt-manage-subscriptions-invoices/ or explore our broader architectural overview on /connect-zoho-billing-to-ai-agents-process-quotes-payment-links/.

Giving a Large Language Model (LLM) read and write access to a sprawling financial ecosystem like Zoho Billing is an engineering challenge. You have to handle OAuth 2.0 token lifecycles, map massive JSON schemas to MCP tool definitions, and deal with strict financial data constraints. Every time Zoho updates an endpoint or changes a payload requirement, you have to update your server code, redeploy, and test the integration.

This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for Zoho Billing, connect it natively to Claude Desktop, and execute complex billing workflows using natural language.

The Engineering Reality of the Zoho Billing API

A custom MCP server is a self-hosted integration layer. While the open MCP standard provides a predictable way for models to discover tools, the reality of implementing it against specialized B2B financial APIs is painful. Zoho Billing is built to manage complex recurring subscriptions, metered billing, project accounting, and localized tax compliance. Its API reflects that deep complexity.

If you decide to build a custom Zoho Billing MCP server, here are the specific integration challenges you will face:

Strict State Transitions and Financial Immutability In a financial system, you cannot simply perform standard CRUD operations on every record. For example, you cannot execute a standard DELETE on an invoice that has payments or credit notes applied. To void an invoice, you must execute a specific state transition endpoint (e.g., create_a_zoho_billing_invoice_void). An LLM has no inherent knowledge of these state machine rules. A managed MCP server exposes tools with strictly defined documentation schemas that explicitly guide the model on which operational endpoints to call based on the resource's current status.

Custom Field Injection and Nested Arrays Zoho Billing handles custom data through complex nested arrays rather than flat key-value pairs. When updating custom fields on an invoice or subscription, the API expects a custom_fields array containing specific label and value objects. Unstructured LLMs frequently hallucinate this schema, attempting to pass flat keys like {"cf_region": "NA"}. Truto solves this by dynamically generating tools directly from integration documentation records, injecting highly specific JSON Schemas that force Claude to construct the exact nested array structure Zoho demands.

Strict API Quotas and Rate Limit Handling Zoho Billing enforces strict API concurrency limits and minute-level rate quotas. If an AI agent attempts to run a heavy pagination loop to pull historical transactions, it will quickly hit a wall. Note on rate limits: Truto does not retry, throttle, or apply backoff on rate limit errors. When the upstream Zoho API returns an HTTP 429, Truto passes that error directly to the caller. However, Truto normalizes the upstream rate limit information into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF spec. The agent framework is responsible for reading these headers and executing the appropriate retry or backoff strategy.

Step 1: Creating the Zoho Billing MCP Server

Truto derives MCP tools dynamically from the underlying Zoho Billing integration. Rather than hand-coding tool definitions, Truto reads the integration's resource configurations and documentation records. If a resource has a documentation record defining its description, query schema, and body schema, it becomes an available MCP tool.

Each MCP server is scoped to a single integrated account (a specific authenticated Zoho tenant). You can generate the MCP server either via the Truto UI or programmatically via the API.

Method A: Via the Truto UI

For ad-hoc agent deployment or internal operations, the UI is the fastest path:

1. Log into Truto and navigate to the Integrated Accounts page.
2. Select the connected Zoho Billing account you want the agent to access.
3. Click the MCP Servers tab.
4. Click Create MCP Server.
5. Configure the server settings (assign a name, select allowed methods like read or write, and set an optional expiration date).
6. Copy the generated secure MCP server URL.

Method B: Via the Truto API

For production applications provisioning AI agents dynamically for end-users, you will generate the MCP server via a REST call. The endpoint validates that the integration has tools available, generates a secure cryptographic token, and stores it in distributed KV storage.

Execute a POST request to /integrated-account/:id/mcp:

curl -X POST https://api.truto.one/integrated-account/YOUR_ACCOUNT_ID/mcp \
  -H "Authorization: Bearer YOUR_TRUTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Finance Ops Agent - Zoho Billing",
    "config": {
      "methods": ["read", "write"],
      "tags": ["invoicing", "expenses"]
    },
    "expires_at": "2026-12-31T23:59:59Z"
  }'

The API returns a payload containing the fully authenticated MCP server URL:

{
  "id": "mcp-7a8b9c0d",
  "name": "Finance Ops Agent - Zoho Billing",
  "config": {
    "methods": ["read", "write"],
    "tags": ["invoicing", "expenses"]
  },
  "expires_at": "2026-12-31T23:59:59.000Z",
  "url": "https://api.truto.one/mcp/t_a1b2c3d4e5f6g7h8i9j0"
}

This URL contains everything Claude needs to authenticate and discover tools. No additional OAuth logic is required on the client side.

Step 2: Connecting the MCP Server to Claude

Once you have the Truto MCP server URL, you must register it with Claude. This allows Claude to handshake with the JSON-RPC endpoint, request the tools/list, and understand the schemas.

Method A: Via the Claude UI

If you are using Claude Desktop or an enterprise workspace with UI connector support:

1. Open Claude and navigate to Settings → Integrations → Add MCP Server.
2. Paste the url generated in the previous step.
3. Click Add.

Claude will immediately ping the endpoint, execute the handshake, and load the Zoho Billing tools into the model's context window.

Method B: Via Manual Configuration File

If you are configuring Claude Desktop locally for development, you will edit the claude_desktop_config.json file. Because Truto's MCP servers communicate over Server-Sent Events (SSE) via HTTP POST, you must use the official remote SSE transport wrapper.

Update your config file (typically located at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

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

Restart Claude Desktop. The application will launch the SSE transport, connect to the Truto MCP router, and expose the Zoho Billing capabilities.

Zoho Billing Hero Tools for Claude

Truto exposes hundreds of underlying endpoints for Zoho Billing. When Claude calls tools/list, it receives a filtered, transformed array of tool objects. Each tool merges the integration's native REST schemas into a flat JSON-RPC input namespace, allowing Claude to seamlessly pass both query and body parameters.

Here are 6 high-leverage hero tools your agents will use most frequently.

List Subscriptions

Tool Name: list_all_zoho_billing_subscriptions

This tool retrieves all recurring subscriptions in the Zoho Billing instance. It supports filtering by customer, reference number, or subscription status. The schema automatically includes cursor pagination instructions, ensuring Claude can paginate through large datasets without hallucinating limit offsets.

"Fetch all active subscriptions in Zoho Billing that are scheduled for renewal next week, and paginate through the results if there are more than 50 records."

Create an Invoice

Tool Name: create_a_zoho_billing_invoice

This tool generates a new manual invoice. It requires detailed nested objects for invoice_items. Because Truto derives the schema directly from the documentation records, Claude understands exactly how to structure the line item arrays, tax percentages, and unit formats without trial and error.

"Create a new invoice for customer ID 109843. Add a line item for 'Enterprise Support SLA' at $1,500 with a quantity of 1, and mark the invoice status as draft."

Track Expenses

Tool Name: create_a_zoho_billing_expense

This tool records operational expenses directly into the billing ledger. It handles complex regional tax settings (like UK VAT or India GST) and can link the expense to a specific billable customer or project via customer_id and project_id.

"Record a new expense of $450 for AWS Server Hosting. Assign it to the 'Cloud Infrastructure' account and mark it as billable to the 'Acme Corp Migration' project."

Manage Project Billing

Tool Name: list_all_zoho_billing_projects

This tool lists active projects, returning metadata about billing types (e.g., fixed cost vs. based on project hours), budget status, and associated users. It is critical for agents auditing time-and-materials contracts.

"Pull a list of all active projects in Zoho Billing. Identify any projects currently billed based on project hours that have exceeded their allocated budget hours."

Log Time Entries

Tool Name: create_a_zoho_billing_projects_timeentry

This tool logs granular time entries against specific projects and tasks. Claude can calculate elapsed time from unstructured notes and push the exact log_date and log_time required to generate billable hour metrics.

"Log a new time entry for the 'Q3 Marketing Site' project. Assign 4 hours to the 'Frontend Development' task for user ID 88712, and ensure it is marked as billable."

Process Payment Refunds

Tool Name: create_a_zoho_billing_payment_refund

This operational tool executes refunds against previously collected payments. It orchestrates the underlying state logic in Zoho, automatically generating the necessary credit note and issuing the refund against it while ensuring ledger integrity.

"Issue a partial refund of $200 for payment ID 554921 due to a service outage dispute. Leave a note indicating this is a goodwill SLA credit."

For the complete tool inventory, including detailed JSON Schemas, parameter types, and custom field structures, consult the Zoho Billing integration page.

Workflows in Action

Connecting an LLM to a financial system unlocks powerful autonomous workflows. Because the MCP router handles the complex data mapping between the flat JSON-RPC input and Zoho's nested REST architecture, Claude can execute multi-step operations reliably.

Workflow 1: Project Billing Reconciliation

Persona: Finance Operations

"Audit the time entries for the 'Website Redesign' project in Zoho Billing. Find all unbilled time entries from last month, calculate the total billable hours, and generate a new draft invoice for the client based on those hours."

sequenceDiagram
    participant User as Finance Ops
    participant Claude as Claude Desktop
    participant MCP as Truto MCP Server
    participant Zoho as Zoho Billing API

    User->>Claude: Audit time entries & generate invoice
    Claude->>MCP: Call list_all_zoho_billing_projects_timeentries
    MCP->>Zoho: GET /projects/timeentries?is_billable=true
    Zoho-->>MCP: Return time entries array
    MCP-->>Claude: JSON-RPC result (time entries)
    Claude->>Claude: Filter unbilled entries & calculate totals
    Claude->>MCP: Call create_a_zoho_billing_invoice
    MCP->>Zoho: POST /invoices (with line items)
    Zoho-->>MCP: 201 Created (Invoice Object)
    MCP-->>Claude: JSON-RPC result (invoice ID)
    Claude-->>User: "Draft invoice #INV-104 created for 45 unbilled hours."

Execution Steps:

1. Claude calls list_all_zoho_billing_projects_timeentries, parsing the flat input to filter for the specific project and date range.
2. The model analyzes the returned array, calculating the total unbilled hours across the filtered entries.
3. Claude constructs the nested invoice_items payload and calls create_a_zoho_billing_invoice to generate a draft invoice for the exact calculated amount.
4. The agent reports the new invoice ID back to the user for final human approval.

Workflow 2: Subscription Cancellation & Refund Processing

Persona: Customer Support

"Cancel Acme Corp's enterprise subscription at the end of the current term, and issue a prorated refund of $500 for their last payment due to the service interruption."

sequenceDiagram
    participant User as Support Agent
    participant Claude as Claude Desktop
    participant MCP as Truto MCP Server
    participant Zoho as Zoho Billing API

    User->>Claude: Cancel Acme Corp sub & refund $500
    Claude->>MCP: Call list_all_zoho_billing_customers
    MCP->>Zoho: GET /customers?search_text=Acme%20Corp
    Zoho-->>MCP: Return customer ID
    MCP-->>Claude: JSON-RPC result
    Claude->>MCP: Call list_all_zoho_billing_subscriptions
    MCP->>Zoho: GET /subscriptions?customer_id=...
    Zoho-->>MCP: Return active subscription & payment ID
    MCP-->>Claude: JSON-RPC result
    Claude->>MCP: Call zoho_billing_subscriptions_cancel
    MCP->>Zoho: POST /subscriptions/{id}/cancel (cancel_at_end=true)
    Zoho-->>MCP: 200 OK
    MCP-->>Claude: JSON-RPC result
    Claude->>MCP: Call create_a_zoho_billing_payment_refund
    MCP->>Zoho: POST /payments/{id}/refunds (amount=500)
    Zoho-->>MCP: 201 Created
    MCP-->>Claude: JSON-RPC result
    Claude-->>User: "Subscription set to cancel at term end. $500 refund processed."

Execution Steps:

1. Claude calls list_all_zoho_billing_customers to locate the exact CRM ID for Acme Corp.
2. The model queries list_all_zoho_billing_subscriptions using the located customer_id to find the active subscription and the most recent payment ID.
3. Claude calls zoho_billing_subscriptions_cancel, ensuring cancel_at_end is set to true to respect the billing term.
4. The model calls create_a_zoho_billing_payment_refund, orchestrating the complex credit note generation and refund logic in a single operation.

Security and Access Control

Giving an AI agent raw access to a financial system requires strict guardrails. Truto's MCP implementation provides four layers of security to ensure agents cannot execute destructive or unauthorized operations:

• Method Filtering (config.methods): Restrict the server to specific operation categories. Setting methods: ["read"] ensures the agent can only execute get and list operations, physically preventing it from creating invoices, modifying subscriptions, or issuing refunds.
• Tag Filtering (config.tags): Scope access to specific functional domains. If you only want an agent handling expenses, you can apply a tag filter so that CRM, subscription, and invoicing tools are completely omitted from the server.
• Secondary Authentication (require_api_token_auth): By default, possessing the MCP URL grants access. By setting require_api_token_auth: true, Truto enforces a second layer of authentication, requiring the calling client to provide a valid Truto API token or session cookie. This ensures the URL cannot be abused if leaked in logs.
• Automatic Expiry (expires_at): Generate ephemeral servers with a strict time-to-live. Truto utilizes Cloudflare KV expirations and Durable Object alarms to automatically purge the token and all associated access at the specified timestamp, perfect for temporary contractor access or limited-duration agent tasks.

Moving Forward with Agentic Billing Operations

Connecting Zoho Billing to Claude transforms an LLM from a passive text generator into an active participant in your financial operations. By utilizing Truto's managed MCP architecture, you bypass the friction of OAuth lifecycles, schema normalization, and server deployment.

Your engineers do not have to write custom integration code to parse Zoho's custom fields or handle state transitions. Truto's documentation-driven tool generation ensures Claude receives the exact schemas required to execute complex project billing, subscription management, and expense tracking workflows flawlessly.

Start building secure, agentic financial integrations today with managed MCP infrastructure.