Connect Cloudbeds to Claude: Automate Billing and Folio Accounting

If you need to connect Cloudbeds to Claude to automate hotel billing, balance transfers, folio adjustments, or complex B2B hospitality invoicing, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's LLM tool calls and the highly structured REST APIs of Cloudbeds. 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-cloudbeds-to-chatgpt-manage-bookings-and-guest-relations/ or explore our broader architectural overview on /connect-cloudbeds-to-ai-agents-sync-property-ops-and-analytics/.

Giving a Large Language Model (LLM) read and write access to a sprawling property management system like Cloudbeds is a severe engineering challenge. You have to handle OAuth 2.0 token lifecycles, map massive nested JSON schemas to MCP tool definitions, and deal with Cloudbeds's strict accounting rules. Every time the upstream API changes a ledger endpoint, 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 Cloudbeds, connect it natively to Claude Desktop, and execute complex financial workflows using natural language.

The Engineering Reality of the Cloudbeds 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 Cloudbeds is painful. You are not just integrating a simple CRUD API - you are integrating an enterprise property management system with strict double-entry accounting rules, asynchronous ledgers, and region-specific fiscalization engines.

If you decide to build a custom MCP server for Cloudbeds, you own the entire API lifecycle. Here are the specific challenges you will face:

Polymorphic Folio Routing In Cloudbeds, financial transactions do not just live on a reservation. They exist within Folios, which are bound by a sourceKind (e.g., RESERVATION, GROUP_PROFILE, HOUSE_ACCOUNT) and a sourceId. Moving transactions between a guest reservation folio and a corporate group folio requires deep state awareness. If you expose raw routing endpoints to an LLM, the model will struggle with the polymorphic entity mapping. Your MCP server must present clear, distinct tools for routing transactions that explicitly require both the ID and the exact entity kind.

Asynchronous Ledger Transfers Cloudbeds enforces strict financial boundaries. Moving a guest's outstanding balance to an Accounts Receivable (AR) ledger for corporate invoicing is not a simple state change. Calling the balance transfer endpoint triggers an asynchronous job, returning an eventId. If an AI agent expects synchronous confirmation, its workflow will break. You must build an abstraction that either polls the event status or properly instructs the LLM on how to track asynchronous jobs.

Country-Specific Fiscalization (GOBL) Issuing invoices in Cloudbeds is governed by regional fiscalization rules (e.g., SAF-T in Portugal, KSeF in Poland). You cannot simply pass a generic JSON blob to generate an invoice. The payload must comply with GOBL (Global Open Business Ledger) structures, and specific fields become required depending on the property's country. Generating an MCP tool schema that accurately reflects these conditional requirements is incredibly complex to maintain manually.

How Truto's Managed MCP Server Works

Truto eliminates the need to build a custom server. Instead of hand-coding tool definitions for every Cloudbeds endpoint, Truto's MCP server dynamically generates tools directly from the integration's resource definitions and documentation records.

The system derives the query and body schemas at runtime. When an MCP client (like Claude) calls a tool, the arguments arrive as a single flat input namespace. Truto's proxy routing automatically splits these arguments into query parameters and JSON body payloads based on the derived schemas, handling the translation seamlessly. Tools are never cached or pre-built, meaning Claude always interacts with the most up-to-date representation of the Cloudbeds API.

Factual note on rate limits: Truto does not retry, throttle, or apply backoff on rate limit errors. When the upstream Cloudbeds API returns an HTTP 429, Truto passes that error directly to the caller. Truto normalizes the upstream rate limit information into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF spec. The caller (or your AI agent framework) is completely responsible for implementing retry logic and backoff. Truto does not automatically retry or absorb rate limit errors.

Step 1: Creating the Cloudbeds MCP Server

You must first generate an MCP server URL linked to a specific Cloudbeds property connection (an Integrated Account). You can do this via the Truto UI or programmatically via the API.

Method A: Via the Truto UI

1. Navigate to the Integrated Accounts page in your Truto dashboard and select your connected Cloudbeds account.
2. Click the MCP Servers tab.
3. Click Create MCP Server.
4. Select your desired configuration. You can optionally filter tools by method (e.g., read, write) or tags.
5. Copy the generated MCP server URL. It will look like https://api.truto.one/mcp/a1b2c3d4e5f6....

Method B: Via the API You can generate servers programmatically, which is essential if you are spinning up multi-tenant agents for your users. Make an authenticated POST request to the Truto API:

curl -X POST https://api.truto.one/integrated-account/{integrated_account_id}/mcp \
  -H "Authorization: Bearer YOUR_TRUTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Cloudbeds Billing Agent",
    "config": {
      "methods": ["read", "write", "custom"]
    }
  }'

The API provisions the underlying edge storage records, validates that the requested filters match available documentation, and returns the secure URL for your MCP client.

Step 2: Connecting Cloudbeds to Claude

Once you have the Truto MCP URL, you connect it to your LLM framework. The URL contains a cryptographic token that securely identifies the exact Cloudbeds tenant environment.

Method A: Via the Claude UI (or ChatGPT UI)

1. If using Claude Desktop / Web: Go to Settings -> Integrations -> Add MCP Server. Paste the Truto MCP URL and click Add.
2. If using ChatGPT: Go to Settings -> Apps -> Advanced settings. Enable Developer Mode. Under Custom Connectors, click Add a new server, name it "Cloudbeds Billing", paste the Truto URL, and save.

Method B: Via Manual Config File (Claude Desktop) For local development or strict environment control, you can add the server to your claude_desktop_config.json file. Because Truto MCP servers speak JSON-RPC over Server-Sent Events (SSE), you use the official MCP SSE transport command.

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

Restart Claude Desktop. The model will automatically execute the tools/list initialization handshake and load the Cloudbeds integration.

Hero Tools for Cloudbeds Accounting

Out of the dozens of endpoints available on the Cloudbeds API, these specific tools offer the highest leverage for automating hospitality finance, billing, and folio operations.

List All Cloudbeds Folios

list_all_cloudbeds_v_1_0_folios Retrieves the logical folio groupings for a specific reservation or group profile. This is required before moving transactions or issuing invoices, as you must identify the correct target folio ID. The agent must pass the sourceId and sourceKind (e.g., RESERVATION).

"Find the active folios for reservation ID 4920194. I need the folio ID for the one designated as the primary billing target."

Search Folio Transactions

list_all_cloudbeds_folios_transactions Retrieves both posted and pending transactions assigned to a specific source. Useful for auditing what a guest actually bought versus what room rate they are paying.

"Get all pending transactions for reservation 4920194. Separate the room charges from the incidental POS charges."

Transfer Balance to Accounts Receivable

create_a_cloudbeds_balance_transfer Transfers a reservation's outstanding balance out of the local guest ledger and into a corporate Accounts Receivable (AR) ledger. This triggers an asynchronous background job and returns an event ID.

"Transfer the $1,250 outstanding balance on reservation 4920194 to the AR ledger ID 8412. Tell me the event ID tracking the transfer."

Add Folio Adjustment

create_a_cloudbeds_post_adjustment Adds an adjustment (positive or negative) to a reservation's financials. When a guest disputes a mini-bar charge or an agent needs to apply a goodwill discount, this tool directly modifies the ledger.

"Apply a $50 negative adjustment to reservation 4920194 for a service recovery discount. Categorize it under 'fee'."

Generate Fiscal Invoice

create_a_cloudbeds_fiscal_documents_invoice Generates a formal fiscal document (invoice) based on the current folio state. This command enforces the strict regional GOBL requirements based on the property's configured country.

"Create a finalized fiscal invoice for reservation 4920194 based on all currently posted transactions. Ensure the status is set to OPEN."

Get Reservations with Rate Details

list_all_cloudbeds_get_reservations_with_rate_details Retrieves the detailed state of a reservation, including the booked room type, the exact daily rate plan, source information, and the current outstanding balance.

"Pull the full rate details and outstanding balance for the guest checking out today named 'Acme Corp'."

For the full inventory of Cloudbeds tools, schemas, and endpoint definitions, visit the Cloudbeds integration page.

Workflows in Action

By chaining these dynamically generated tools together, Claude can execute complex, multi-step accounting workflows that normally require human intervention in the Cloudbeds UI.

1. Corporate Billing and AR Transfer

When a corporate client checks out, their balance needs to be routed out of the guest ledger and into a corporate Accounts Receivable account for bulk 30-day invoicing. An agent can automate this entirely.

"Reservation 4920194 belongs to the 'Acme Corp' group. Check their outstanding balance, transfer the entire balance to their corporate AR ledger (ID 9912), and confirm the transfer event ID."

Execution sequence:

1. list_all_cloudbeds_get_reservations_with_rate_details (Retrieves the reservation, confirming an outstanding balance of $2,400).
2. list_all_cloudbeds_v_1_0_folios (Confirms the source folio structure for the reservation).
3. create_a_cloudbeds_balance_transfer (Posts the $2,400 transfer to AR ledger 9912 and extracts the async event_id from the payload).

sequenceDiagram
    participant Claude as Claude Desktop
    participant MCP as Truto MCP Server
    participant API as Cloudbeds API
    
    Claude->>MCP: Call list_reservations_with_rate_details
    MCP->>API: GET /reservations?id=4920194
    API-->>MCP: Balance: $2400
    MCP-->>Claude: JSON response
    Claude->>MCP: Call create_balance_transfer
    MCP->>API: POST /balance-transfers
    API-->>MCP: { "eventId": "evt_88192a" }
    MCP-->>Claude: JSON response

2. Disputed Charge Resolution and Invoicing

A guest contacts support claiming they were incorrectly charged for parking. The agent must verify the charge, apply a ledger adjustment to wipe it out, and then generate the final invoice.

"The guest on reservation 4920194 is disputing a $35 parking charge. Check their pending folio transactions. If the charge exists, post a -$35 adjustment to remove it, then generate their final fiscal invoice."

Execution sequence:

1. list_all_cloudbeds_folios_transactions (Queries the folio for the specific $35 parking line item).
2. create_a_cloudbeds_post_adjustment (Posts a -$35 adjustment specifically targeting the reservation to clear the charge).
3. create_a_cloudbeds_fiscal_documents_invoice (Triggers the fiscal engine to generate the clean invoice, passing sourceKind: 'RESERVATION' and sourceId: 4920194).

Security and Access Control

Giving an AI agent access to core financial data requires strict boundaries. Truto provides multiple layers of security at the MCP token level:

• Method Filtering: You can strictly limit the MCP server to read-only operations. Setting methods: ["read"] during token creation ensures the LLM can call get and list endpoints, but fundamentally cannot trigger create_a_cloudbeds_balance_transfer or adjustments.
• Tag Filtering: Integrations support granular grouping via config.tool_tags. You can restrict an MCP server to only expose tools tagged as billing or reservations, hiding administrative or settings tools entirely.
• Extra Authentication: Setting require_api_token_auth: true means possession of the MCP URL is not enough. The client must also pass a valid Truto API token in the Authorization header to execute tools.
• Automatic Expiration: The expires_at attribute allows you to generate short-lived MCP servers. Once the timestamp passes, edge storage records automatically expire and the server ceases to function, making it ideal for temporary contractor access or ephemeral CI/CD test agents.

Automating Hospitality Finance with MCP

Building a custom integration layer for Cloudbeds means constantly fighting with polymorphic routing, async event polling, and GOBL fiscal configurations. By using Truto to generate your MCP server, you offload the entire maintenance burden. Truto translates Cloudbeds's strict accounting schemas into a flat, predictable JSON-RPC interface that LLMs natively understand.

Instead of managing OAuth tokens and reading API changelogs, your engineering team can focus on orchestrating intelligent agents that actually resolve guest disputes, route corporate billing, and close the books faster.