Skip to content

Connect Karbon to ChatGPT: Manage work items, billing, and contacts

Learn how to connect Karbon to ChatGPT using Truto's auto-generated MCP servers. Automate work items, log expenses, and manage client groups with natural language.

Nachi Raman Nachi Raman · · 9 min read
Connect Karbon to ChatGPT: Manage work items, billing, and contacts

If you need to connect Karbon to ChatGPT to automate accounting workflows, manage client work items, or track billable time and expenses, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between ChatGPT's function calls and Karbon's specialized REST APIs.

If your team uses Claude, check out our guide on connecting Karbon to Claude or explore our broader architectural overview on connecting Karbon to AI Agents.

Giving a Large Language Model (LLM) read and write access to a practice management platform like Karbon is a serious engineering undertaking. You either spend weeks building, hosting, and securing a custom MCP server to map LLM JSON arguments into Karbon's specific payload structures, or you use a managed infrastructure layer to generate it instantly.

This guide breaks down exactly how to use Truto to generate a secure, authenticated MCP server for Karbon, connect it natively to ChatGPT, and execute complex workflows - like onboarding clients and generating work items - using natural language.

The Engineering Reality of the Karbon API

Building a custom MCP server means owning the entire API integration lifecycle. While the open MCP standard provides a predictable way for models to discover tools, implementing it against Karbon's API surface requires handling several domain-specific integration quirks that break standard CRUD assumptions.

If you decide to build a custom MCP server for Karbon, you must account for the following architectural realities:

OData Pagination and Filtering Constraints

Karbon's API relies heavily on OData conventions. Unlike modern REST APIs that use cursor-based pagination, Karbon pages data using $skip and $top query parameters. The $top value is strictly capped - typically returning a maximum of 100 records per request. Your custom MCP server must implement logic to translate an LLM's open-ended request ("Get all my clients") into batched OData queries, track the $skip offsets, and aggregate the value arrays before returning the payload to the LLM context window. Failure to manage this will result in truncated data or hallucinatory responses.

Asymmetric Update Payloads (Keys vs IDs)

Karbon separates identifying a record for retrieval from identifying a record for a partial update. While standard GET, PUT, and DELETE operations route via the standard id in the URL path, partial PATCH updates often require passing a named query field - such as WorkItemKey, ContactKey, or ClientGroupKey - directly in the payload. An LLM natively assumes that the id used to fetch a record is the exact same field name used to update it. Your MCP server must explicitly define JSON Schemas that separate standard URL IDs from payload Keys to prevent the LLM from executing malformed PATCH requests.

OData String Escaping

Karbon allows developers to query records using User-Defined Identifiers. However, under OData syntax rules, if an identifier contains a single quote, it must be escaped by writing it twice (e.g., O'Connor becomes O''Connor). LLMs do not inherently know OData escaping rules. If you do not write a middleware parser in your custom MCP server to intercept and sanitize these query strings, the LLM's requests will fail with 400 Bad Request errors.

Step-by-Step: Connecting Karbon to ChatGPT via MCP

Rather than building and hosting this infrastructure yourself, you can use Truto to dynamically generate a managed MCP server. This server handles authentication, derives tool schemas directly from Karbon's API documentation, and routes the requests securely.

Step 1: Connect your Karbon Account

First, you need to establish an authenticated connection to Karbon.

  1. In the Truto dashboard, navigate to Integrated Accounts -> New Integrated Account.
  2. Select Karbon and complete the OAuth flow.
  3. Note your integrated_account_id. Truto securely stores the resulting tokens and handles all future token refreshes automatically.

Step 2: Generate the MCP Server

Truto allows you to generate an MCP server URL scoped exclusively to this integrated account. You can do this via the dashboard or programmatically via the API.

Method A: Via the Truto UI

  1. Navigate to the integrated account page for your Karbon connection.
  2. Click the MCP Servers tab.
  3. Click Create MCP Server.
  4. Select your desired configuration (e.g., filtering for specific tags like work_items or setting the method to read).
  5. Copy the generated MCP server URL.

Method B: Via the API You can provision the server programmatically by POSTing to the Truto API. This is useful for multi-tenant applications dynamically provisioning agents for end-users.

curl -X POST https://api.truto.one/integrated-account/<INTEGRATED_ACCOUNT_ID>/mcp \
  -H "Authorization: Bearer $TRUTO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Karbon ChatGPT MCP",
    "config": {
      "methods": ["read", "write"],
      "tags": ["work_items", "contacts", "timesheets"]
    }
  }'

The API returns a payload containing a single, secure url (e.g., https://api.truto.one/mcp/a1b2c3d4e5f6...). This URL encodes the routing logic and the hashed authentication token.

Step 3: Connect the MCP Server to ChatGPT

Now that you have your MCP server URL, you must register it with ChatGPT.

Method A: Via the ChatGPT UI

  1. Open ChatGPT and navigate to Settings -> Apps -> Advanced settings.
  2. Enable Developer mode (MCP capabilities are currently behind this toggle).
  3. Under MCP servers / Custom connectors, click to add a new server.
  4. Provide a name (e.g., "Karbon Integration") and paste the Truto MCP URL.
  5. Click Save. ChatGPT will immediately perform a handshake, call tools/list, and populate its context with the available Karbon tools.

Method B: Via Manual Config File (for local/custom clients) If you are running an automated script, a custom LangChain agent, or a specialized desktop client, you can connect to the remote Truto server using the standard Server-Sent Events (SSE) transport adapter provided by the MCP SDK.

Create an mcp.json file:

{
  "mcpServers": {
    "karbon": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "--url",
        "https://api.truto.one/mcp/<YOUR_SECURE_TOKEN>"
      ]
    }
  }
}

Security and Access Control

Giving an AI agent access to financial and practice management data requires strict governance. Truto provides four native security mechanisms to constrain the generated MCP server:

  • Method Filtering (config.methods): Restrict the server to safe operations. Passing ["read"] ensures the LLM can only execute GET or list operations, physically preventing it from modifying or deleting Karbon data.
  • Tag Filtering (config.tags): Scope the available tools to specific business domains. By passing ["contacts", "organizations"], you prevent the LLM from discovering or accessing timesheet or billing endpoints entirely.
  • Secondary Authentication (require_api_token_auth): By default, the MCP URL acts as a bearer token. For higher security, setting require_api_token_auth: true forces the connecting client to also pass a valid Truto API token in the Authorization header, preventing unauthorized access if the URL is leaked.
  • Time-to-Live (expires_at): Pass an ISO datetime to create a short-lived MCP server. Once the timestamp passes, the edge storage invalidates the token, and background alarms permanently delete the configuration. This is ideal for temporary auditing workflows.

A factual note on API rate limits: Truto does not retry, throttle, or apply exponential backoff on rate limit errors. When the upstream Karbon API returns an HTTP 429, Truto passes that error directly to the caller and normalizes the rate limit information into standard headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) following the IETF specification. The calling MCP client or agent must handle its own backoff logic.

Hero Tools for Karbon

Truto automatically generates tools for every documented Karbon endpoint. Below are six high-leverage hero tools that transform ChatGPT into a capable practice management assistant.

list_all_karbon_work_items

Retrieves a paginated list of work items from your tenant. This tool supports query parameters to filter the results, allowing the LLM to find active client work or overdue tasks.

"Fetch the latest 50 work items in Karbon. Are there any items currently marked as blocked or overdue?"

get_single_karbon_contact_by_id

Retrieves the full profile of a specific contact using their ContactKey. The LLM can use this to pull phone numbers, email addresses, and associated business card details before drafting client communications.

"Look up the contact details for the ID provided in the previous step and draft an email reminding them to upload their Q3 tax documents."

create_a_karbon_work_item

Allows the LLM to generate new work items and assign them to specific team members. Requires the assignee's email address, a title, the client key, client type, and a start date.

"Create a new work item for 'Annual Tax Return - 2026' for client key C-12345. Set the start date to tomorrow and assign it to sarah@ourfirm.com."

create_a_karbon_note

Attaches a new note to any Karbon entity - such as a Work Item, Contact, Organization, or Client Group. This is heavily used by AI agents to log meeting summaries or phone call transcripts directly into the client record.

"Take this meeting transcript, summarize the key action items, and create a note on the organization record for Acme Corp outlining the next steps."

create_a_karbon_expense

Logs a new expense against a Work Item, Contact, or Organization. The LLM must supply the timeline, expense date, value, billable value, and a description. Note that expenses cannot be updated or deleted via the API once created.

"Log a new billable expense for $150.00 against work item W-9876 for 'Courier Services'. The expense date is today."

list_all_karbon_timesheets

Retrieves a paginated list of timesheets. The LLM can filter this list by start date, end date, user key, work item keys, and status to generate utilization reports or check for missing time entries.

"List all timesheets submitted for the current week. Summarize the total hours logged by user U-555 and identify any timesheets still in a draft status."

(For the complete inventory of available Karbon tools and their JSON schemas, view the Karbon integration page.)

Workflows in Action

Connecting ChatGPT to Karbon unlocks complex, multi-step practice management workflows. Here are three real-world scenarios demonstrating how the LLM orchestrates these tools.

Scenario 1: Client Onboarding and Work Orchestration

When a new client signs a contract, the AI agent can fully provision their profile and initial project structure in Karbon.

"We just signed a new client, Jane Doe (jane.doe@example.com). Create a new contact record for her, create a client group for her family, and generate an initial onboarding work item assigned to me starting today."

Execution Steps:

  1. create_a_karbon_contact: ChatGPT posts the payload with FirstName, LastName, and email, receiving the new ContactKey.
  2. create_a_karbon_client_group: ChatGPT creates the client group structure for family-level reporting.
  3. update_a_karbon_contact_by_id: The agent executes an update to link the new contact to the newly created client group.
  4. create_a_karbon_work_item: Finally, the agent creates the onboarding task, setting the assignee and linking it to the client key.
sequenceDiagram
    participant User as User
    participant GPT as ChatGPT
    participant Truto as Truto MCP Server
    participant Karbon as Karbon API
    
    User->>GPT: "Onboard new client Jane Doe..."
    GPT->>Truto: Call create_a_karbon_contact
    Truto->>Karbon: POST /Contacts
    Karbon-->>Truto: Returns ContactKey
    Truto-->>GPT: Contact ID
    
    GPT->>Truto: Call create_a_karbon_work_item
    Truto->>Karbon: POST /WorkItems
    Karbon-->>Truto: Returns WorkItemKey
    Truto-->>GPT: Work Item ID
    
    GPT-->>User: "Jane Doe is onboarded and work item is created."

Scenario 2: Meeting Ingestion and Time Tracking

AI agents excel at parsing unstructured data and converting it into structured practice management logs.

"Review these raw notes from my meeting with Acme Corp. Summarize them, save the summary as a note on their organization profile, and log 1.5 hours of billable time against their active consulting work item."

Execution Steps:

  1. list_all_karbon_organizations: ChatGPT searches for "Acme Corp" to retrieve the correct OrganizationKey.
  2. list_all_karbon_work_items: ChatGPT queries work items filtered by the Acme Corp client key to find the active consulting item.
  3. create_a_karbon_note: The agent synthesizes the raw text into a professional summary and posts it to the organization record.
  4. update_a_karbon_estimate_summary_by_id / Time Entry: The agent logs the 1.5 hours of billable time against the retrieved work item.

Scenario 3: Billing Audit and Expense Syncing

ChatGPT can proactively audit projects to ensure no billable expenses fall through the cracks before invoicing.

"Audit the active work item 'Q1 Financial Audit' for Stark Industries. Check if any new expenses have been logged this week, list them out, and draft a status update email for the lead accountant."

Execution Steps:

  1. list_all_karbon_work_items: ChatGPT finds the specific work item for Stark Industries.
  2. list_all_karbon_estimate_summaries: The agent queries the estimate summaries and expenses linked to that WorkItemKey.
  3. Data Processing: ChatGPT analyzes the returned arrays, filtering for expenses logged within the trailing 7 days.
  4. Response Generation: The LLM formats a clean markdown table of the expenses and drafts the requested email text for the user to review.

Moving from Chat to Production

Connecting ChatGPT to Karbon via Truto's MCP server eliminates the need to manually build OAuth handlers, study OData syntax, or write custom mapping scripts. By relying on dynamically generated, documentation-driven tools, your AI agents always have an accurate, up-to-date representation of your Karbon environment.

Whether you are building internal automation tools for your accounting firm, or developing a multi-tenant SaaS product that requires interacting with user financial data, Truto provides the secure routing infrastructure required to scale.

FAQ

Does Truto automatically retry rate-limited Karbon API requests?
No. Truto does not retry, throttle, or apply backoff on rate limit errors. When Karbon returns an HTTP 429, Truto passes that error directly to the caller, normalizing the headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF spec. The calling client is responsible for handling retries.
Can I restrict ChatGPT to only read data from Karbon?
Yes. When generating the MCP server in Truto, you can pass a configuration object with 'methods': ['read']. This filters out all write, update, and delete tools, ensuring the AI agent can only query data.
How do I filter the Karbon tools available to the LLM?
You can use method filtering (e.g., 'read', 'write', 'custom') and tag filtering (e.g., 'work_items', 'contacts') when creating the MCP server via the Truto API or UI. The server will dynamically generate only the tools that match your criteria.
How do I connect the Truto MCP server to ChatGPT?
You can connect it via the ChatGPT UI by enabling Developer mode and adding the Truto MCP URL as a Custom Connector, or by using a manual configuration file with the @modelcontextprotocol/server-sse command for custom desktop or CI environments.

More from our Blog