A
licenseA
qualityD
maintenanceEnables AI clients to seamlessly take HubSpot actions and interact with HubSpot data, allowing users to create/update CRM records, manage associations, and gain insights through natural language.
22
19 npm
MIT
hawksoft-mcp
by sanjibani
The HawkSoft MCP server lets you read and write HawkSoft insurance agency data from any MCP client (Claude, Cursor, etc.) using natural language or structured tool calls.
Read / Query
List agencies & offices — retrieve all agencies and their associated offices
Get a single client — fetch full client details including people, contacts, claims, policies, and invoices
Bulk fetch — retrieve up to 200 clients in a single call
Incremental sync — list clients modified since a given timestamp, with optional office filtering or deleted-record inclusion
Search by policy number — look up a client using an exact policy number match
Write
Create log notes — append structured activity notes (phone calls, emails, carrier touchpoints, conversation summaries) to a client record, with optional follow-up task assignment
Create attachments — attach base64-encoded files (PDFs, images, documents) to a client record, optionally linked to a policy
Record receipts — log one or more payments against client invoices, with automatic log note creation
Reference / Utility
List channels — access all 56 HawkSoft LogAction channel codes with friendly names and categories (also available as a resource at
hawksoft://channels)Audit logging — every tool call generates a JSONL audit trail for compliance
Practical Use Cases
Pre-call client briefs (pull full history before a call)
Auto-documenting carrier or insured touchpoints as structured log notes
Attaching certificates of insurance or declaration pages to the right client record
Batch activity reporting and end-of-day digests
Reconciliation — surfacing clients with outstanding invoices and recording payments
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@hawksoft-mcp Show me clients changed since Monday and group by carrier"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
hawksoft-mcp
Model Context Protocol (MCP) server for HawkSoft Insurance Agency Management.
Talk to your HawkSoft data from Claude, Cursor, or any MCP client — read clients, policies, and claims, and write back log notes, attachments, and receipts in plain English.
Built against the HawkSoft Partner API v3.0. No existing MCP for HawkSoft — this is the first.
What you can do with it
You: "Show me every HawkSoft client modified since Monday and group them by carrier."
Claude: *calls list_changed_clients, then get_client for each, then summarises*
You: "Find the policy POR83741 and log a phone call with the insured about their renewal."
Claude: *searches by policy → opens client → calls create_log_note with channel=5*Other things agents do well with this server:
Pre-call briefs — pull the client's full history (policies, claims, prior conversations) before a phone call
Auto-document carrier touchpoints — every email/phone with a carrier becomes a structured log note
Batch activity reporting — "give me a weekly summary of every client I called"
Certificate of insurance / declaration page intake — attach PDFs straight into the right client record
Reconciliation help — surface clients with outstanding invoices, draft follow-ups
Related MCP server: Zava Insurance MCP Server
Install
pip install -e .Or just use uv / pipx if you prefer.
Configure
You need HawkSoft Partner API credentials — username + password issued by HawkSoft after your app is approved through their Partner Program.
export HAWKSOFT_USERNAME="your-vendor-username"
export HAWKSOFT_PASSWORD="your-vendor-password"You can also drop these in a .env file (see .env.example).
Who uses this server?
Two audiences:
Approved HawkSoft API Partners building tools for independent agencies. Your vendor credentials work directly.
Independent agencies doing their own custom integration work. HawkSoft has explicitly opened this path — see the V3.0 launch post:
"any agencies who build their own custom API integrations" can use the V3.0 Partner API directly.
If you're an agency and don't have vendor credentials yet, email
opportunities@hawksoft.comto get set up.
Use with Claude Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"hawksoft": {
"command": "hawksoft-mcp",
"env": {
"HAWKSOFT_USERNAME": "your-vendor-username",
"HAWKSOFT_PASSWORD": "your-vendor-password"
}
}
}
}Restart Claude Desktop. You should see 9 new tools + 1 resource (hawksoft://channels).
Use with Claude Code
claude mcp add hawksoft -- hawksoft-mcp \
--env HAWKSOFT_USERNAME=your-user --env HAWKSOFT_PASSWORD=your-passUse with Cursor
Add a new MCP server in Cursor settings pointing at the hawksoft-mcp command with the same env vars.
Tools
Tool | Type | What it does |
| Read | List agency IDs that have subscribed to your vendor app |
| Read | List offices for a given agency |
| Read | Incremental sync — clients changed since a timestamp |
| Read | Full client record (details, people, contacts, claims, policies) |
| Read | Fetch up to 200 clients in one call |
| Read | Find a client by exact policy number |
| Write | Add a log note + optional follow-up task |
| Write | Attach a base64 file (PDF / image / doc) to a client |
| Write | Record one or more payments against invoices |
| Reference | All 56 HawkSoft LogAction codes |
Plus one resource:
URI | Description |
| Full channel catalog (value / label / category) |
Common patterns
Pre-call brief
User: I'm about to call client 4231. Give me the full picture.
Agent: list_changed_clients(agency_id=1, as_of="2020-01-01")
→ [4231, ...]
get_client(agency_id=1, client_id=4231)
→ returns details, policies, people, prior claims
summarise: 2 personal auto policies, 1 umbrella, no recent claims, last contact 2 weeks ago about a billing question...Document a phone call after it happens
User: I just got off a call with the Johnsons about their renewal. Auto policy. Renewal looks good, they want to add a teenage driver next month.
Agent: search_client_by_policy(agency_id=1, policy_number="AUTO-7741")
→ finds client
create_log_note(
agency_id=1,
client_id=client_id,
channel="Phone From Insured",
description="Renewal discussion; wants to add teen driver next month",
body="Discussed upcoming renewal. Customer satisfied with current rate. Mentioned adding a teenage driver in ~30 days. Set follow-up task for CSR to send driver addition intake form.",
task_title="Send teen driver intake form",
task_description="Customer mentioned adding teenage driver to auto policy next month. Send standard intake form.",
task_due_date="2026-07-15",
task_assigned_to_role="CSR",
)End-of-day activity digest
User: What did I do with clients today?
Agent: create_log_note(...) for each touchpoint during the day,
then for the digest: get_clients_bulk(client_numbers=[recent_ids])
and summarise.Channel catalog
Channels use friendly names everywhere in the API — never the integer. Phone From Insured, Email To Carrier, etc. The full 56-entry catalog is exposed via the list_channels_tool tool and the hawksoft://channels resource.
API coverage
HawkSoft endpoint | MCP tool |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Full HawkSoft Partner API v3.0 docs: https://partner.hawksoft.app/v3/api.html
Development
# install with dev deps
pip install -e ".[dev]"
# run tests
pytest
# run server locally (stdio)
hawksoft-mcpSecurity & audit logging
Every tool call emits a structured JSONL audit record (one JSON object per line) to stderr by default. Each record has:
ts, tool, request_id, args, result_size, is_error, error_type, duration_msSensitive fields are redacted before logging: password, api_key, token,
access_token, refresh_token, authorization, client_secret. Long string
values are truncated to 256 characters.
To redirect to a file (e.g. for shipping to your log aggregator), set:
export HAWKSOFT_MCP_AUDIT_LOG=/var/log/hawksoft-mcp/audit.jsonl
hawksoft-mcpThe audit log is fail-open: if the configured file cannot be opened (missing directory, permission denied), records fall back to stderr and the tool still returns its result.
If you don't have HawkSoft credentials yet, the client will raise a clear error on first call — the server doesn't try to connect at import time.
License
MIT — see LICENSE.
Contributing
Issues + PRs welcome. Two things that always help:
More tools. If you spot a HawkSoft endpoint we missed (or one that needs a friendlier wrapper), open an issue.
Better prompts. The most useful thing you can share is a real example of an insurance workflow this helped you with — we collect these in
/examples.
See also
Available Tools
10 toolscreate_attachmentA
Attach a base64-encoded file (PDF, image, doc) to a client record.
Args:
agency_id: HawkSoft agency ID.
client_id: HawkSoft client number.
channel: Channel name or LogAction int (use list_channels for the catalog).
desc: One-line description of the file.
log_note: Log note text tied to this attachment.
file_name: File name including extension, e.g. "declaration_page.pdf".
file_b64: Base64-encoded file contents — NO data: URL prefix.
policy_id: Optional policy GUID to link to.
ref_id: Idempotency UUID (auto-generated if omitted).
ts: ISO 8601 timestamp (defaults to now).
task_title, task_description, task_due_date, task_assigned_to_role,
task_assigned_to_email, task_category: Optional follow-up task.
Inputs: desc (required), channel (required), file_b64 (required), log_note (required), +12 more. Returns: result
create_log_noteA
Append a log note (and optional follow-up task) to a client's record.
The single most useful write tool — call this whenever the agent does anything that should be visible in HawkSoft: a phone call, an email, a conversation summary, a carrier touch.
Args:
agency_id: HawkSoft agency ID.
client_id: HawkSoft client number.
channel: Friendly channel name (e.g. "Phone From Insured") or LogAction int.
description: One-sentence summary shown in the activity feed.
body: Full note text. May be multi-line.
ref_id: Unique UUID for idempotency. Auto-generated if omitted.
ts: ISO 8601 timestamp. Defaults to now (UTC).
policy_id: Optional policy GUID to link the note to.
policy_index: Optional 1-based index on the policy.
action: Optional action code.
task_title: Set to create a follow-up task.
task_description: Task description.
task_due_date: ISO 8601 due date.
task_assigned_to_role: One of SpecifiedUser, Producer, CSR, Agent1, Agent2, Agent3.
task_assigned_to_email: Required when assigned_to_role is SpecifiedUser.
task_category: Optional category label.
Inputs: body (required), channel (required), agency_id (required), client_id (required), +12 more. Returns: result
create_receiptsA
Record one or more payments received by a client.
Each receipt applies to one or more invoices. A log note is automatically created and linked. Optionally create a follow-up task.
Args:
agency_id: HawkSoft agency ID.
client_id: HawkSoft client number.
receipts: List of receipts. Each item must include:
- channel: channel name or int
- logNote: text of the log note
- total: total amount received
- invoices: list of {"invoiceId": "<guid>", "amount": <float>}
Optional per receipt: refId, ts, policyId, officeId, payMethod, task.
Inputs: receipts (required), agency_id (required), client_id (required). Returns: result
get_clientA
Fetch full details for a single client.
Returns the full client object — details, people, contacts, claims, policies
by default. Use include to narrow the response and save bandwidth.
Args: agency_id: HawkSoft agency ID. client_id: HawkSoft client number. include: Sections to include: details, people, contacts, claims, policies, invoices.
Inputs: agency_id (required), client_id (required), include. Returns: result
get_clients_bulkA
Fetch multiple clients in one call (up to 200 per request).
Args: agency_id: HawkSoft agency ID. client_numbers: List of client numbers (1–200 per call).
Inputs: agency_id (required), client_numbers (required). Returns: result
list_agenciesA
List agency IDs that have subscribed to your HawkSoft vendor app.
Returns an array of integer agency IDs. Each represents an independent insurance agency that has opted in to data sharing with your app via the HawkSoft License Management Portal.
Inputs: no named parameters. Returns: result
list_changed_clientsA
List client IDs that changed since a given timestamp.
The workhorse for syncing. Pass an as_of ISO 8601 timestamp to get only
clients modified after that point; omit it to get all clients. Then use
get_client or get_clients_bulk on each ID.
Args:
agency_id: HawkSoft agency ID.
as_of: ISO 8601 timestamp (e.g. 2026-06-01T00:00:00Z). Omit for full list.
office_id: Restrict to a specific office.
include_deleted: Include soft-deleted clients.
Inputs: agency_id (required), as_of, office_id, include_deleted. Returns: result
list_channels_toolA
Return all 56 HawkSoft channel codes with friendly names and categories.
Use this to discover the right channel value to pass into create_log_note,
create_attachment, or create_receipts.
Inputs: no named parameters. Returns: result
list_officesB
List offices configured under an agency.
Args: agency_id: HawkSoft agency ID (from list_agencies).
Inputs: agency_id (required). Returns: result
search_client_by_policyA
Find a client by exact policy number match.
Useful when an agent has a policy number from a carrier but not the HawkSoft client number. Returns all clients (usually 1) holding that policy. Exact match only — no partial or fuzzy search.
Args: agency_id: HawkSoft agency ID. policy_number: Exact policy number. include: Sections to include.
Inputs: agency_id (required), policy_number (required), include. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
A4/5.0
Scored across 10 tools
Disambiguation5/5
Each tool targets a distinct resource or action: create_attachment, create_log_note, create_receipts for different logging operations; get_client and get_clients_bulk for client retrieval (single vs. bulk); list_agencies, list_channels_tool, list_offices for different listings; search_client_by_policy for policy-based search; and list_changed_clients for sync. No two tools have overlapping purposes.
Naming Consistency4/5
All tool names follow a consistent verb_noun snake_case pattern (e.g., create_log_note, get_client, list_agencies). The only minor deviation is list_channels_tool which appends '_tool', but it is still readable and clearly indicates its purpose.
Tool Count5/5
With 10 tools, the set is well-scoped for a HawkSoft server covering client retrieval, logging activities (notes, attachments, receipts), and listing utilities (agencies, offices, channels, changed clients). Each tool earns its place without being excessive or sparse.
Completeness4/5
The core workflows are covered: retrieving clients (single, bulk, by policy), adding log notes, attachments, and receipts, and listing supporting entities. Minor gaps exist, such as no update or delete operations for logs or client data, but agents can likely accomplish typical tasks without dead ends.
Maintenance
ActivityInactive
ResponsivenessNo recent community issues
Related MCP Connectors
Ask your Quickbase apps in plain language. Read-only by default; writes need human approval.
Hutsenpiller Insurance clients: let your AI view policies, ID cards, documents, request changes.
Insurance agency AI policy drafts, data-rule checks, workflows, and pricing.
Build and run agents and automations across hundreds of apps using natural language.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables management of insurance claims, inspections, and contractors through interactive UI widgets and data tools. Users can view claim dashboards, update statuses, and query service provider information using natural language.-
- FlicenseAqualityDmaintenanceEnables interaction with IntelliMatch recruiting and iSuite insurance systems through spec-driven MCP tools, allowing natural language queries for candidate search, policy management, claims, and workflows.28-
- AlicenseAqualityCmaintenanceLets an AI assistant read and write business records in plain language, including looking up people, creating and updating tasks, logging time, and pulling utilization reports through a synthetic ops platform or an optional ClickUp adapter.8MIT