Connect Bexio to Claude: Sync Contacts, Sales & Payroll Records

If your team needs to connect Bexio to Claude to automate sales pipeline management, reconcile payroll absences, or orchestrate complex quote-to-cash operations, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's tool calls and Bexio's REST API. 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-bexio-to-chatgpt-manage-invoices-projects-accounting/ or explore our broader architectural overview on /connect-bexio-to-ai-agents-automate-billing-tasks-inventory/.

Giving a Large Language Model (LLM) read and write access to a sprawling business management ecosystem like Bexio is an engineering challenge. You have to handle OAuth 2.0 token lifecycles, map massive JSON schemas to MCP tool definitions, and deal with Bexio's strict API quotas. Every time Bexio updates an endpoint or deprecates a legacy resource, 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 Bexio, connect it natively to Claude Desktop, and execute complex workflows using natural language.

The Engineering Reality of the Bexio 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 APIs is painful. Bexio is a comprehensive ERP, CRM, and payroll system built for Swiss SMEs, and its API reflects that strict domain complexity.

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

The Knowledge Base (KB) Item State Machine Bexio handles quotes, orders, deliveries, and invoices as interconnected "KB Items." These items operate on a rigid state machine. For example, you cannot simply update an invoice to a "sent" state if it is currently "issued" - there are specific lifecycle endpoints for transitioning documents. Quotes can only be accepted if they are in a pending state (kb_item_status_id = 2). If an LLM attempts to accept a drafted quote without first issuing it, the Bexio API will reject the request. A managed MCP server exposes these state transitions as explicit tools (e.g., bexio_quotes_issue, bexio_quotes_accept), guiding the LLM through the correct operational flow rather than letting it guess the state machine.

Complex Pricing Overrides and Conversions When converting a quote into an order or an invoice, the data mapping is not 1:1. Bexio enforces four distinct pricing models: type_hourly_rate_service, type_hourly_rate_employee, type_hourly_rate_project, and type_fix. When an agent creates an invoice from a quote, it must pass a carefully structured payload to instruct Bexio on exactly how to carry over these specific hourly rates. Exposing this via MCP requires highly annotated JSON schemas so the LLM understands exactly which override flags to apply during document conversion.

Deprecated Fields and Silent Failures APIs evolve, and Bexio has several legacy fields that can trip up automated agents. For example, when fetching or creating contacts and payroll employees, the legacy address and street fields are technically deprecated but often still present in response payloads. Creating a contact now requires the structured fields street_name and house_number. If you feed a raw, uncurated OpenAPI spec to an LLM, it will likely hallucinate requests using the deprecated address string, resulting in validation errors. Managed MCP tools curate the schema, explicitly rejecting deprecated fields and enforcing the required structured inputs.

Handling API Rate Limits Bexio enforces strict concurrency and rate limits to protect its infrastructure. It is critical to understand that Truto does not retry, throttle, or apply backoff on rate limit errors. When the upstream Bexio API returns an HTTP 429 (Too Many Requests), Truto passes that error directly to the caller. Truto normalizes the upstream rate limit information into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) following the IETF specification. Your client implementation - whether it is Claude Desktop or a custom LangGraph agent - is entirely responsible for observing these headers and implementing its own retry or backoff logic. Do not expect the MCP server to absorb these errors for you.

Connecting Bexio to Claude

To bridge the gap between Claude and Bexio, we need to generate an MCP server URL and provide it to the Claude client. Truto handles the OAuth credential management and dynamic tool generation automatically.

Step 1: Generate the MCP Server

An MCP server in Truto is scoped to a single integrated account (a specific tenant's connected Bexio instance). You can generate the server URL via the UI or the API.

Method A: Via the Truto UI

1. Navigate to the integrated account page for the target Bexio connection.
2. Click the MCP Servers tab.
3. Click Create MCP Server.
4. Select your desired configuration (e.g., restrict to "read" methods, or specific tags like "crm").
5. Copy the generated MCP server URL (it will look like https://api.truto.one/mcp/a1b2c3d4e5f6...).

Method B: Via the API You can programmatically generate this server for your end-users. Send 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": "Bexio Sales and CRM AI",
    "config": {
      "methods": ["read", "write", "custom"],
      "tags": ["crm", "billing"]
    }
  }'

The API validates the configuration, generates a cryptographically secure token, stores the routing rules in edge KV storage, and returns the ready-to-use URL.

Step 2: Connect the Server to Claude

Once you have the URL, you need to register it with your Claude client. MCP communicates over JSON-RPC 2.0.

Method A: Via the Claude UI

1. Open Claude's Settings.
2. Navigate to the Integrations or Connectors tab.
3. Click Add MCP Server.
4. Paste your Truto MCP URL and click Add. Claude will immediately execute an initialize handshake and call tools/list to discover the available Bexio operations.

Method B: Via the Manual Config File For Claude Desktop, you can manually define the connection in your claude_desktop_config.json file. Because Truto's MCP servers are accessible over HTTP, we use a Server-Sent Events (SSE) bridge utility provided by the official Model Context Protocol organization.

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

Restart Claude Desktop. The application will spawn the SSE transport bridge and fetch the latest tool schemas derived directly from the Bexio documentation.

Hero Tools for Bexio

When Claude connects to the Bexio MCP server, it does not see a generic CRUD interface. It sees highly descriptive, operation-specific tools automatically derived from integration documentation. Here are the highest-leverage tools available for Bexio automation.

Search Contacts (bexio_contacts_search)

Instead of paginating through thousands of records, this tool allows Claude to post specific filter criteria (e.g., field name_1, value Meyer, criteria =) to instantly retrieve targeted contact data. This is critical for resolving named entities in natural language prompts to actual Bexio UUIDs.

"Find the contact record for Acme Corp in Zurich and return their internal contact ID and primary email address."

Convert Quote to Invoice (bexio_quotes_create_invoice)

This tool handles the complex transition from a sales proposal to a finalized billing document. It accepts the source quote_id and allows the LLM to optionally override how service, employee, and project hourly rates are calculated during the conversion.

"Take the accepted quote ID 4059 and convert it into a draft invoice. Ensure the service hourly rate is carried over exactly as defined in the quote."

Log Employee Timesheets (create_a_bexio_timesheet)

Time tracking is heavily regulated in professional services. This tool allows an agent to record billable hours against specific projects, tracking IDs, and service milestones, ensuring accurate downstream payroll and client invoicing.

"Log 4 hours of billable time for user ID 12 on the 'Q3 Website Overhaul' project under milestone ID 5. Add a note saying 'Frontend component refactoring'."

Query Payroll Absences (list_all_bexio_payroll_absences)

Essential for HR automation and project capacity planning. This tool retrieves absence records for specific employees, detailing the reason, start date, end date, and whether the absence was for a half-day or resulted in continued pay.

"Pull the absence records for employee ID 45 for this month. Calculate how many paid sick hours they have recorded so far."

Register Invoice Payment (bexio_invoices_create_payment)

Closing the accounts receivable loop. Once a bank transfer clears, this tool attaches a payment record to a specific invoice, adjusting its pending balance and moving the document state toward completion.

"Record a payment of 4,500 CHF against invoice ID 8892. Set the execution date to today and note that the funds cleared via wire transfer."

To view the complete inventory of available tools, required schemas, and field definitions, visit the Bexio integration page.

Workflows in Action

With the MCP server connected and the tools exposed, Claude can orchestrate complex, multi-step operations that previously required point-to-point scripts or human intervention. Here is how specific personas use these capabilities.

Scenario 1: Quote-to-Cash Automation (Sales Ops / Finance)

When a sales representative closes a deal, the resulting quote must be converted into an invoice, issued, sent to the client, and eventually marked as paid. Doing this manually across dozens of accounts is a massive operational bottleneck.

"Find the accepted quote for 'Alpine Logistics Enterprise Renewal'. Convert it into an invoice. Once created, mark the invoice as sent. Then, log a full payment against that invoice to close it out."

How the Agent Executes This:

1. Calls bexio_quotes_search with the query filter for "Alpine Logistics Enterprise Renewal" to retrieve the quote ID.
2. Calls bexio_quotes_create_invoice passing the retrieved quote ID to generate the draft invoice.
3. Calls bexio_invoices_mark_as_sent to finalize the document status.
4. Calls bexio_invoices_create_payment to attach the payment payload, balancing the ledger.

The Result: The LLM traverses the strict Bexio KB Item state machine flawlessly, converting a sales proposal into recognized revenue and providing a summary confirmation to the user.

Scenario 2: Employee Leave & Timesheet Reconciliation (Project Manager)

Resource allocation requires cross-referencing HR availability with CRM project tracking. If a project manager needs to assign tasks, they must first ensure the employee is actually working that week.

"Check if employee ID 45 has any planned absences this week. If their schedule is clear, log 8 hours of billable time to the 'Zurich Datacenter Migration' project for today."

How the Agent Executes This:

1. Calls list_all_bexio_payroll_absences filtering by the employee ID and the current date range.
2. Evaluates the response. If the array is empty (no absences), it proceeds.
3. Calls bexio_projects_search to find the exact internal ID for the "Zurich Datacenter Migration" project.
4. Calls create_a_bexio_timesheet attaching the employee ID, project ID, and the 8-hour charge constraint.

The Result: Claude acts as an autonomous resource planner, strictly adhering to HR constraints before modifying project financials.

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

    User->>Claude: Check absences, log 8 hours to Zurich project.
    Claude->>Truto: Call list_all_bexio_payroll_absences (emp_id: 45)
    Truto->>Bexio: GET /payroll/absences
    Bexio-->>Truto: Return [] (No absences)
    Truto-->>Claude: Return empty array
    Claude->>Truto: Call bexio_projects_search (name: "Zurich Datacenter")
    Truto->>Bexio: POST /pr_project/search
    Bexio-->>Truto: Return project_id: 99
    Truto-->>Claude: Return project data
    Claude->>Truto: Call create_a_bexio_timesheet (emp_id: 45, project_id: 99, hours: 8)
    Truto->>Bexio: POST /timesheet
    Bexio-->>Truto: 201 Created
    Truto-->>Claude: Success
    Claude-->>User: Timesheet logged successfully.

Security and Access Control

Giving an AI agent access to ERP and payroll data requires strict governance. Truto's MCP architecture provides several layers of access control built directly into the token payload, ensuring the LLM only accesses what it explicitly needs.

• Method Filtering: When creating the server, you can restrict access by HTTP method categories. Passing methods: ["read"] ensures the LLM can only query data (e.g., search contacts, list bills) and completely removes destructive tools like delete_a_bexio_contact_by_id from the schema.
• Tag Filtering: You can isolate the agent to specific functional domains. Passing tags: ["crm"] will only expose contact and account tools, keeping the agent entirely walled off from sensitive payroll or ledger endpoints.
• Secondary Authentication (require_api_token_auth): For high-security environments, possession of the MCP URL is not enough. Enabling this flag forces the MCP client to also pass a valid Truto API token in the Authorization header, enforcing identity validation on every JSON-RPC request.
• Time-to-Live (expires_at): You can generate ephemeral servers for contractor workflows or temporary audits by defining an ISO datetime expiration. Once the clock hits, the edge KV storage automatically evicts the token, permanently revoking the agent's access.

Moving Forward

Connecting Claude to Bexio via MCP transforms a complex, state-machine-heavy ERP into an intuitive, natural language interface. Instead of forcing your engineers to study Bexio's pricing override fields or deprecated address schemas, the managed MCP server curates the documentation, normalizes the tool definitions, and handles the cryptographic routing automatically.

The result is an AI agent that can confidently traverse the quote-to-cash lifecycle, audit payroll systems, and manage CRM entities - all while adhering to the strict access controls dictated by your infrastructure.

By leveraging dynamic tool generation, you insulate your AI workflows from upstream breaking changes. When Bexio deprecates a V1 resource, the documentation updates, the MCP schema adapts, and your agent continues operating seamlessly. This is the architecture required to scale LLM automation in enterprise environments.