Skip to content

Connect HawkSoft to ChatGPT: Manage Client Profiles and Log Notes

Learn how to connect HawkSoft to ChatGPT using a managed MCP server. This guide covers setup, API quirks, and automated workflows for agency management.

Uday Gajavalli Uday Gajavalli · · 9 min read
Connect HawkSoft to ChatGPT: Manage Client Profiles and Log Notes

If you need to connect HawkSoft to ChatGPT to automate agency management workflows, retrieve policy information, or log client interactions, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between ChatGPT's function calling capabilities and HawkSoft'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 Claude, check out our guide on connecting HawkSoft to Claude or explore our broader architectural overview on connecting HawkSoft to AI Agents.

Giving a Large Language Model (LLM) read and write access to an insurance agency management system like HawkSoft is a massive engineering challenge. You have to handle complex relational data payloads, map specialized endpoints to MCP tool definitions, and deal with unusual API response formats. Every time the integration requires new capabilities, your custom server code must be updated, redeployed, and tested.

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

The Engineering Reality of the HawkSoft 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, implementing it against HawkSoft's highly specific agency API presents a few distinct hurdles.

If you decide to build a custom MCP server for HawkSoft, you own the entire API lifecycle. Here are the specific integration challenges that break standard CRUD assumptions when working with HawkSoft:

Unusual Response Formats for Mutations

Standard REST APIs typically return a JSON object representing the newly created resource. HawkSoft deviates from this on several mutation endpoints. For example, when creating a log note (POST /api/v1/lognotes), HawkSoft often answers with a plain text message such as HTTP 200 The log was created successfully. or HTTP 202 The request was saved and the log will be created next time the agency is connected to the cloud. LLMs expect structured JSON. If your MCP server does not gracefully wrap or handle these plain-text responses, the JSON-RPC parsing in the ChatGPT client will fail. Truto handles this by passing the text response back as a cleanly formatted text file within the MCP result array.

Root-Level JSON Array Payloads

LLM tool calling excels at generating JSON objects with key-value pairs. However, specific HawkSoft endpoints - such as creating receipts - require the request body to be a raw JSON array of objects, rather than a single parent object. Instructing an LLM to directly output a raw array as the root of a function call is unreliable and often violates strict JSON schema validation. To solve this, the Truto MCP server maps a virtual items array property from the LLM into the raw JSON array expected by HawkSoft's proxy API, abstracting away the structural friction.

The 25 Requests Per Second Rate Limit Cliff

HawkSoft enforces a strict rate limit of 25 requests per second. While generous for human-driven operations, autonomous agents executing concurrent searches or bulk processing can hit this ceiling instantly. When the limit is exceeded, the upstream API returns an HTTP 429 response.

Note on handling rate limits: Truto does not automatically retry, throttle, or apply backoff on rate limit errors. Instead, Truto normalizes the upstream rate limit information into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification. When HawkSoft returns a 429, Truto passes that exact error and the standardized headers back to the caller. It is the responsibility of the MCP client (or your orchestration layer) to read these headers and implement the appropriate retry and backoff logic.

Complex Change-Tracking Pagination

Retrieving a full list of clients in HawkSoft is not a standard GET /clients?page=2 operation. HawkSoft uses a specialized sync pattern. First, you must call the "Changed Clients" endpoint, optionally providing an asOf date, which returns a list of Client IDs. You must then take those IDs and feed them into a bulk POST endpoint (hawk_soft_clients_bulk_get) in batches of up to 200 to read the actual client records. Teaching an LLM to orchestrate this multi-step synchronization loop requires precise tool definitions and schema descriptions.

Creating the HawkSoft MCP Server

Truto's MCP servers turn any connected HawkSoft account into an MCP-compatible tool server dynamically. Tools are generated directly from the integration's resource definitions and documentation records. You can create the server using either the Truto UI or the API.

Method 1: Via the Truto UI

The dashboard provides a fast, no-code path to generate an MCP server url.

  1. Log into your Truto dashboard and navigate to your Integrated Accounts.
  2. Select the connected HawkSoft account you want to expose to ChatGPT.
  3. Click the MCP Servers tab.
  4. Click Create MCP Server.
  5. Configure the server name, filter by specific methods or tags, and set an optional expiration date.
  6. Click Save and copy the generated MCP server URL (e.g., https://api.truto.one/mcp/a1b2c3d4...).

Method 2: Via the Truto API

For teams building programmatic AI agent deployment, you can generate the MCP server via a single POST request. This provisions the server and returns the secure token URL.

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": "HawkSoft ChatGPT Assistant",
    "config": {
      "methods": ["read", "write"],
      "tags": ["clients", "logs", "receipts"]
    },
    "expires_at": "2026-12-31T23:59:59Z"
  }'

The API validates the configuration, stores the hashed token in secure KV storage, and returns a JSON payload containing your url.

Connecting the MCP Server to ChatGPT

Once you have the Truto MCP URL, you need to connect it to your ChatGPT interface.

Method 1: Via the ChatGPT UI

If you are using ChatGPT Enterprise, Business, Pro, or Plus with Developer Mode enabled, you can add custom connectors directly in the interface.

  1. Open ChatGPT and go to Settings -> Apps -> Advanced settings.
  2. Ensure Developer mode is enabled.
  3. Under MCP servers or Custom connectors, select Add.
  4. Enter a name (e.g., "HawkSoft (Truto)").
  5. Paste the Truto MCP URL into the Server URL field.
  6. Click Save. ChatGPT will perform an initialization handshake, discover the HawkSoft tools, and make them available in your chat.

Method 2: Via Manual Configuration File (SSE)

For local development or custom client implementations using the @modelcontextprotocol/server-sse transport, you can configure your MCP client to connect using a standard JSON configuration.

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

When the client starts, it connects via HTTP POST and utilizes JSON-RPC 2.0 to handle the initialize, tools/list, and tools/call methods dynamically based on your HawkSoft integration.

Hero Tools for HawkSoft

Truto automatically derives MCP tools from the HawkSoft integration based on available API endpoints and documentation schemas. Here are the highest-leverage tools available for your AI agents.

Tool name: hawk_soft_clients_search Searches an agency's clients. Currently, the primary supported search criteria is the Policy Number. This is essential for locating records when a customer calls in with only their policy ID. It returns an empty list when nothing matches.

"Search HawkSoft for the client associated with policy number POL-998234."

Get Single HawkSoft Client by ID

Tool name: get_single_hawk_soft_client_by_id Reads a single client record using their unique HawkSoft Client ID. This endpoint supports 'Client Includes', allowing you to fetch nested policy, vehicle, and coverage data in a single request.

"Fetch the full profile for HawkSoft client ID 88392, including all active policies."

Create a HawkSoft Log Note

Tool name: create_a_hawk_soft_log_note Creates a log note (and optionally a task) on a client record. This is heavily used by agents to document phone calls, emails, or AI-driven interactions. Required fields include the client number, channel, and the note text itself.

"Log a note on client 88392 stating that I left a voicemail regarding their upcoming auto policy renewal."

Create a HawkSoft Client

Tool name: create_a_hawk_soft_client Creates a new client in the specified agency. If BusinessDetail is passed in the payload, the client is classified as a Commercial customer; otherwise, they are a Personal customer.

"Create a new personal client profile for John Doe with the phone number 555-0199. Include a log note saying this was an inbound lead."

List All HawkSoft Changed Clients

Tool name: list_all_hawk_soft_changed_clients Retrieves a list of client IDs that have changed since a specific date. When called without an asOf parameter, it returns every client ID. This tool is the first step in synchronizing agency data into external systems.

"Get a list of all HawkSoft client IDs that have been updated since yesterday morning."

Create a HawkSoft Receipt

Tool name: create_a_hawk_soft_receipt Records a payment received by a client. A log note is automatically created and linked to the receipt, and an optional task can be generated for an agent to review.

"Record a premium receipt of $150.00 for client 88392 and flag it for review by the billing team."

To see the complete tool inventory and detailed JSON schemas, visit the HawkSoft integration page.

Workflows in Action

With the MCP server connected to ChatGPT, you can orchestrate complex, multi-step operations strictly through natural language prompts.

Scenario 1: The Client Lookup and Interaction Log

An insurance agent finishes a phone call with a client who provided a policy number. The agent wants ChatGPT to locate the client and immediately log the details of the call.

"Find the HawkSoft client with policy number PA-556112. Once you find them, add a log note saying the insured called to update their garaging address, and I advised them that underwriting would review the change."

Execution Steps:

  1. ChatGPT calls hawk_soft_clients_search passing policyNumber: "PA-556112".
  2. The proxy API returns the matching client array, identifying the client ID as 10544.
  3. ChatGPT calls create_a_hawk_soft_log_note with the client_number: 10544, setting the channel to "Phone", and passing the dictated note.
  4. The agent receives a confirmation that the text log was created successfully.

Scenario 2: Processing Inbound Premium Payments

An agency receives an email containing payment confirmation details for a commercial client. The user asks ChatGPT to apply the payment.

"Client 99201 just sent a wire transfer for $1,200 for their general liability policy. Create a receipt for this amount and create a task for the commercial lines manager to review the payment allocation."

sequenceDiagram
    participant User as User
    participant ChatGPT as ChatGPT
    participant TrutoMCP as Truto MCP
    participant HawkSoft as HawkSoft API

    User->>ChatGPT: "Create receipt for client 99201..."
    ChatGPT->>TrutoMCP: Call create_a_hawk_soft_receipt
    TrutoMCP->>HawkSoft: POST /api/v1/receipts<br>(with raw JSON array)
    HawkSoft-->>TrutoMCP: HTTP 200 Success
    TrutoMCP-->>ChatGPT: Result Confirmation
    ChatGPT-->>User: "Receipt created and task assigned."

Execution Steps:

  1. ChatGPT interprets the prompt and identifies the required schema for create_a_hawk_soft_receipt.
  2. It structures the items array with the payment amount, method (Wire), client ID (99201), and the task assignment flag.
  3. Truto receives the tool call, unwraps the items array, and forwards the raw array payload to HawkSoft.
  4. Truto returns the HawkSoft confirmation payload to ChatGPT, which summarizes the action for the user.

Security and Access Control

Exposing an agency management system to an AI agent requires strict security boundaries. Truto MCP servers provide four layers of configuration to lock down access:

  • Method Filtering: Restrict the server to specific operation types. Set config.methods to ["read"] to allow searching and fetching clients, while entirely blocking create, update, or delete operations.
  • Tag Filtering: Group tools by domain. By passing config.tags: ["clients", "logs"], you prevent the LLM from discovering or interacting with sensitive financial endpoints like receipts or agency configurations.
  • API Token Authentication: By default, the cryptographically secure MCP URL is all that is required to connect. By setting require_api_token_auth: true, Truto forces the client to also provide a valid API bearer token in the headers, adding a secondary layer of identity verification.
  • Time-to-Live (TTL): Use the expires_at field to create ephemeral MCP servers. This is highly effective for granting temporary system access to automated agents for a specific nightly batch job. Once expired, Truto automatically cleans up the database record and invalidates the edge KV storage.

Automate HawkSoft Workflows with Truto

Connecting HawkSoft to ChatGPT shouldn't require you to build custom pagination loops, parse plain-text HTTP 202 responses, or maintain infrastructure just to translate LLM JSON arguments into legacy API structures.

By using Truto to generate a managed MCP server, you abstract away the API quirks and immediately equip your AI agents with the tools they need to search policies, sync client lists, and log daily activities safely.

FAQ

Does Truto automatically retry rate limited requests from HawkSoft?
No. HawkSoft has a strict rate limit of 25 requests per second. Truto maps any HTTP 429 responses into standardized IETF rate limit headers and passes the error back to the caller. Your AI agent or orchestration layer must handle the backoff and retry logic.
How do I filter which HawkSoft tools ChatGPT can use?
When creating the MCP server via the Truto UI or API, you can pass a configuration object containing `methods` (e.g., "read", "write") and `tags` (e.g., "clients", "logs"). The server will only generate tools that match these constraints.
How does Truto handle HawkSoft's raw JSON array requirements for receipts?
Truto's dynamically generated tool schemas expose an `items` array property to the LLM. When the tool is called, Truto seamlessly unwraps this and forwards the raw JSON array to the HawkSoft proxy API, ensuring compliance with both the LLM and the upstream API.
Can I expire a HawkSoft MCP server automatically?
Yes. You can supply an `expires_at` timestamp when generating the server. Once the time is reached, Truto automatically tears down the edge KV storage and database records, instantly revoking access.

More from our Blog