Connect HawkSoft to Claude: Sync Agency Data and Process Receipts
A complete engineering guide to connecting HawkSoft to Claude. Learn how to generate a managed MCP server, handle HawkSoft's delta syncs, and automate workflows.
If your team needs to connect HawkSoft to Claude to automate insurance agency operations, sync client profiles, or process policy receipts, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's natural language tool calls and HawkSoft'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 connecting HawkSoft to ChatGPT or explore our broader architectural overview on connecting HawkSoft to AI Agents.
Giving a Large Language Model (LLM) read and write access to a sprawling agency management system like HawkSoft is a significant engineering challenge. You have to handle complex token lifecycles, map massive insurance data schemas to MCP tool definitions, and deal with HawkSoft's highly specific API constraints. Every time HawkSoft updates an endpoint or deprecates a legacy data model, 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 HawkSoft, connect it natively to Claude Desktop, and execute complex agency management 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 over JSON-RPC 2.0, the reality of implementing it against specialized B2B APIs is painful. HawkSoft is built to manage commercial and personal insurance policies, complex agency structures, and audit logs. Its API design reflects that complexity.
If you decide to build a custom HawkSoft MCP server, here are the specific integration challenges you will face:
The Two-Step Delta Sync Pattern
HawkSoft does not allow you to simply query a /clients?updated_since=... endpoint and receive full client objects in return. Instead, reading modified records requires a two-step sequence. First, you must call the endpoint mapped to list_all_hawk_soft_changed_clients with an asOf parameter to retrieve an array of client IDs. Then, you must take those IDs and execute an unusual HTTP POST request against the bulk retrieval endpoint (hawk_soft_clients_bulk_get) to actually read the client data in batches of up to 200. Left to its own devices, an LLM will almost always hallucinate standard GET requests for this operation. A managed MCP server forces the model to adhere to this strict two-step pattern via precise tool schemas.
Constrained Search Parameters
Most CRMs allow you to search for records by name, email, or phone number. The HawkSoft API is much stricter. The search endpoint (hawk_soft_clients_search) currently only supports searching by policyNumber. If an LLM tries to execute a search using a customer's last name, the API will reject it. Your MCP layer must explicitly define policyNumber as the sole required parameter in the JSON Schema, preventing Claude from wasting context tokens on failed API calls.
Asynchronous Logging and Non-JSON Responses HawkSoft treats log notes seriously for compliance reasons. When you POST to create a log note, the API does not always return a standard HTTP 200 with a JSON representation of the new object. If the agency is not actively connected to the cloud, the API will return an HTTP 202 indicating the request was saved and will be synchronized later. Furthermore, the response is often raw text (e.g., "The log was created successfully.") rather than JSON. Your MCP server must be capable of parsing non-JSON responses and surfacing these asynchronous states clearly to the LLM.
Strict Rate Limiting and Error Handling
HawkSoft enforces a strict rate limit of 25 requests per second. If you exceed this, the API returns an HTTP 429 Too Many Requests error. It is important to note that Truto does not retry, throttle, or apply backoff on rate limit errors. When the upstream API returns HTTP 429, Truto passes that error directly back to the caller. Truto normalizes the upstream rate limit info into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification. The caller (in this case, your Claude client or orchestration framework) is entirely responsible for implementing retry logic and exponential backoff.
How to Generate the HawkSoft MCP Server
Truto dynamically generates MCP tools based on the resources and documentation available for an integration. To expose HawkSoft to Claude, you need to create an MCP server scoped to a specific HawkSoft integrated account. You can do this via the Truto UI or programmatically via the API.
Method 1: Via the Truto UI
If you are setting this up manually for an internal team, the dashboard is the fastest route:
- Log into your Truto account and navigate to the Integrated Accounts page.
- Select your connected HawkSoft account.
- Click on the MCP Servers tab.
- Click Create MCP Server.
- Configure the server (give it a name, select allowed methods like
readorwrite, and apply any necessary tags). - Click Save and copy the generated MCP server URL (e.g.,
https://api.truto.one/mcp/a1b2c3d4...).
Method 2: Via the Truto API
If you are building an AI product and need to provision MCP servers for your users programmatically, you can use the Truto API. The API validates that the integration has tools available, generates a secure token, and returns a ready-to-use URL.
Execute a POST request to /integrated-account/:id/mcp:
curl -X POST https://api.truto.one/integrated-account/{integrated_account_id}/mcp \
-H "Authorization: Bearer YOUR_TRUTO_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "HawkSoft Production MCP",
"config": {
"methods": ["read", "write", "custom"]
}
}'Response:
{
"id": "mcp-12345678",
"name": "HawkSoft Production MCP",
"config": { "methods": ["read", "write", "custom"] },
"expires_at": null,
"url": "https://api.truto.one/mcp/xyz987654321..."
}Store the url - this is the only piece of information Claude needs to connect to the server.
How to Connect the MCP Server to Claude
Once you have your Truto MCP server URL, you must register it with your Claude environment. Because Truto's MCP servers communicate over HTTP using Server-Sent Events (SSE) or direct POSTs depending on the client, configuration is minimal.
Method A: Via the Claude UI
If you are using Claude Desktop or an enterprise workspace that supports visual connector management:
- Open Claude and navigate to Settings -> Integrations (or Connectors depending on your tier).
- Click Add MCP Server or Add custom connector.
- Paste the Truto MCP URL generated in the previous step.
- Click Add.
Claude will immediately execute the initialize and tools/list JSON-RPC commands against the Truto endpoint. Within seconds, Claude will understand how to interact with your HawkSoft instance.
Method B: Via Manual Config File
If you are running Claude Desktop locally for development, you can register the server by editing your claude_desktop_config.json file. Truto provides a bridge package to handle the SSE transport layer required by Claude Desktop.
Open your config file (typically located at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS) and add the following:
{
"mcpServers": {
"hawksoft-truto": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-sse",
"https://api.truto.one/mcp/xyz987654321..."
]
}
}
}Restart Claude Desktop. The application will boot the local server-sse proxy, which manages the connection between Claude's internal architecture and Truto's remote JSON-RPC endpoint.
Security and Access Control
Exposing an agency management system to an autonomous agent requires strict security boundaries. Truto MCP servers provide several mechanisms to scope access:
- Method Filtering (
methods): You can restrict an MCP server to only perform specific operation types. Settingmethods: ["read"]ensures the LLM can only executegetandlistoperations, making it impossible for the agent to accidentally delete a client profile or overwrite a log note. - Tag Filtering (
tags): HawkSoft endpoints can be grouped by functional area. By passingtags: ["billing"]during server creation, you can limit the exposed tools to only those related to receipts and invoices. - API Token Enforcement (
require_api_token_auth): By default, the cryptographically secure token in the MCP URL is sufficient for authentication. Setting this flag totrueforces the client to also pass a valid Truto API token in theAuthorizationheader, adding a second layer of security. - Automatic Expiry (
expires_at): If you are spinning up a temporary agent to audit data, you can set an ISO 8601 datetime. Once the timestamp passes, the server is automatically destroyed.
HawkSoft Hero Tools for Claude
Truto dynamically translates HawkSoft's API documentation into MCP-compliant JSON Schema. When Claude requests the tool list, it receives these schemas, complete with enhanced pagination instructions. Here are the highest-leverage tools available for HawkSoft automation.
list_all_hawk_soft_changed_clients
This tool is critical for data synchronization. It returns a list of client IDs that have changed since a specific date. If you omit the date, it returns all client IDs in the agency.
"Claude, query HawkSoft for all client profiles that have been updated since last Friday. Give me the raw list of IDs so we can fetch their details in the next step."
hawk_soft_clients_bulk_get
Because HawkSoft restricts bulk reading, this tool acts as the second phase of the delta sync. It accepts a JSON array of up to 200 clientNumbers (IDs) and returns the full client objects.
"Take the 45 client IDs we just retrieved and use the bulk get tool to pull their full profiles. Summarize which ones have missing contact information."
hawk_soft_clients_search
This tool searches an agency's clients. Due to API constraints, it specifically requires a policyNumber to execute the lookup. It returns an empty list if nothing matches.
"Search HawkSoft for the client associated with policy number 'POL-998877'. Return their primary address and current active status."
create_a_hawk_soft_log_note
Log notes are the lifeblood of insurance compliance. This tool creates a note (and optionally a task) attached to a client profile. The LLM handles passing the required client_number, channel, and note fields.
"Log a note on client ID 10450 stating that the customer called to inquire about flood insurance rates. Mark the channel as 'Phone' and set a follow-up task for tomorrow."
create_a_hawk_soft_client
This tool provisions a new client in the specified agency. The schema dictates that if the BusinessDetail object is provided, HawkSoft treats the record as a Commercial customer; otherwise, it defaults to a Personal line.
"Create a new commercial client profile for 'Acme Corp'. Use the address provided in our chat history and ensure the BusinessDetail object is populated."
create_a_hawk_soft_receipt
This tool records a payment received by a client. It creates a linked log note and optionally assigns a review task. The schema expects a JSON array of receipt objects. If partial failures occur in the batch, the tool surfaces the errors for the agent to review.
"Process these three premium payments as receipts for client 90210. Link them to the auto policy renewal and create a review task for the billing team."
For the complete tool inventory, including pagination parameters, required fields, and nested schema references, visit the HawkSoft integration page.
Workflows in Action
Connecting HawkSoft to Claude allows you to build sophisticated, multi-step workflows. Here are examples of how different personas can leverage this integration.
Scenario 1: The Automated Policy Audit
An Agency Auditor needs to review recent client changes and ensure that all new commercial clients have proper log notes detailing their initial risk assessment.
"Find all HawkSoft clients modified since yesterday. Fetch their full profiles, identify the commercial accounts, and verify if they have a risk assessment log note. If any are missing, generate a summary report."
Execution Steps:
- Claude calls
list_all_hawk_soft_changed_clientspassing yesterday's date as theasOfargument, returning an array of IDs. - Claude batches those IDs and calls
hawk_soft_clients_bulk_get. - The model parses the returned data, identifying profiles where the
BusinessDetailobject is present (indicating commercial status). - Claude cross-references the log notes on those profiles and outputs a formatted markdown report of non-compliant accounts.
sequenceDiagram
participant Auditor
participant Claude Desktop
participant TrutoMCP as Truto MCP Server
participant HawkSoftAPI as HawkSoft API
Auditor->>Claude Desktop: "Find modified commercial clients..."
Claude Desktop->>TrutoMCP: Call tool: list_all_hawk_soft_changed_clients
TrutoMCP->>HawkSoftAPI: GET /changed_clients
HawkSoftAPI-->>TrutoMCP: Array of Client IDs
TrutoMCP-->>Claude Desktop: Returns IDs
Claude Desktop->>TrutoMCP: Call tool: hawk_soft_clients_bulk_get (IDs)
TrutoMCP->>HawkSoftAPI: POST /clients/bulk
HawkSoftAPI-->>TrutoMCP: Client Profiles JSON
TrutoMCP-->>Claude Desktop: Returns Client Data
Claude Desktop-->>Auditor: Generates markdown reportScenario 2: Policy Search and Interaction Logging
An Account Manager finishes a phone call with a client regarding a specific policy and needs the AI to handle the administrative overhead.
"I just spoke with the holder of policy POL-55443. They are moving to a new house next month. Find the client in HawkSoft and add a log note detailing the upcoming address change so the processing team is aware."
Execution Steps:
- Claude calls
hawk_soft_clients_searchpassingpolicyNumber: "POL-55443". - The tool returns the client profile, from which Claude extracts the
client_number. - Claude calls
create_a_hawk_soft_log_noteusing the extractedclient_number, setting thechannelto "Phone", and passing the natural language summary into thenotefield. - Claude informs the Account Manager that the log note was successfully created.
Scenario 3: Batch Receipt Processing
A Billing Specialist receives a CSV of daily premium payments and asks Claude to record them in the system.
"I am pasting a list of 5 premium payments for client 12201. Please create receipts for all of them in HawkSoft and assign a review task to the billing queue."
Execution Steps:
- Claude parses the unstructured text/CSV provided in the prompt.
- It structures the data to match the
create_a_hawk_soft_receiptbody schema, mapping amounts and dates to the required JSON array. - Claude calls
create_a_hawk_soft_receiptpassing theclient_numberand theitemsarray. - Truto proxies the request to HawkSoft. If one receipt fails (e.g., invalid format), HawkSoft returns the error, which Truto passes back. Claude can then inform the user which specific payment failed while confirming the rest.
Moving Beyond Point-to-Point Integration
Building an AI agent that interfaces with an agency management system like HawkSoft requires more than just API keys. You need a system that translates undocumented quirks—like text-based responses and POST-driven read operations—into strictly typed schemas that an LLM can understand.
By leveraging a managed MCP server through Truto, you bypass the infrastructure headache of building JSON-RPC layers, handling OAuth tokens, and writing boilerplate validation code. Instead, you map HawkSoft's complex insurance data models directly into Claude's context window, allowing your team to focus on building agentic workflows rather than maintaining API wrappers.
FAQ
- How do I deal with HawkSoft's rate limits when using an AI agent?
- HawkSoft strictly enforces a 25 request per second rate limit. When this limit is exceeded, Truto passes the HTTP 429 error directly back to the caller along with standard IETF rate limit headers (`ratelimit-limit`, `ratelimit-remaining`, `ratelimit-reset`). Your AI agent or framework is responsible for implementing retry and exponential backoff logic.
- Can I search for HawkSoft clients by name using Claude?
- No. The HawkSoft API's client search endpoint currently only supports searching by `policyNumber`. Truto's MCP schema enforces this constraint, preventing Claude from attempting unsupported search parameters.
- How do I limit what Claude can do inside HawkSoft?
- When creating the Truto MCP server, you can apply method filtering (e.g., `methods: ["read"]`) to block write operations, or tag filtering to limit tools to specific resource groups. You can also require an additional API token for authentication.