NowCerts MCP Server

A comprehensive Model Context Protocol (MCP) server that provides AI assistants with access to all NowCerts API endpoints, plus integration templates for VAPI voice AI and N8N automation.

Overview

This MCP server exposes 100+ NowCerts API endpoints plus external insurance data APIs as tools that can be used by AI assistants like Claude, VAPI voice agents, and N8N workflows. It handles OAuth 2.0 authentication automatically and provides a seamless interface to the NowCerts insurance management platform, along with integrations for Fenris household data, Smarty address validation, NHTSA vehicle information, and AskKodiak commercial insurance classification.

Repository Structure

Features

MCP Server

• Complete API Coverage: All 100+ NowCerts endpoints exposed as MCP tools

• Automatic Authentication: OAuth 2.0 password grant flow with automatic token refresh

• 129+ Lines of Business: Dynamic discovery of all insurance products

• 80+ Insurance Carriers: Dynamic carrier discovery and management

• 25+ Entity Types: Agents, Insureds, Policies, Claims, Prospects, Drivers, Vehicles, and more

• External API Integrations: Fenris household data, Smarty address validation, NHTSA vehicle data, AskKodiak commercial classification

• Smart Token Caching: Fenris OAuth tokens cached and auto-renewed (70% faster)

• Type-Safe: Built with TypeScript for reliability

• Multiple Transports: Stdio (local), SSE (remote), HTTP (remote)

AI Assistant Integrations

• VAPI Voice AI: Pre-built prompts and scripts for insurance quote phone calls

• N8N Automation: System prompts for chat, SMS, and email workflows

• Conversational Design: Natural language processing optimized for insurance workflows

• Multi-Channel Support: Phone, chat, SMS, and email using the same MCP tools

Installation

Prerequisites

• Node.js 20 or higher

• NowCerts API credentials (username and password)

• Optional: Fenris API credentials for household data prefill

• Optional: Smarty credentials for address validation

• Optional: NHTSA tools work without credentials (public API)

Setup

1. Clone or download this repository

2. Install dependencies:

3. Build the TypeScript code:

Configuration

Environment Variables

Required for Basic Functionality

Required for External API Integrations

For Fenris household data prefill functionality:

For Smarty address verification:

Note: External API credentials are optional. The server will work without them, but tools like fenris_prefillHousehold and smarty_verifyAddress will return errors if credentials are not provided.

Claude Desktop Configuration

The server supports two modes of operation:

Option 1: Local Mode (Default - Stdio Transport)

Add the server to your Claude Desktop configuration file:

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

Option 2: Remote Mode (SSE/HTTP Transport)

For remote access or when running the server on a different machine:

1. Start the server in SSE mode:

2. Connect from Claude Desktop using Custom Connector:

In Claude Desktop, use the "Custom Connector" feature with the SSE endpoint URL:

• Local: http://localhost:3000/sse

• Remote: https://your-domain.com/sse

3. Docker deployment (recommended for production):

For running alongside existing Docker services with automatic SSL:

See DEPLOYMENT_GUIDE.md for:

• Integration with existing reverse proxies (Traefik, nginx-proxy)

• Standalone deployment with systemd

• SSL/HTTPS configuration

• Multiple deployment options

4. For production deployments without Docker:

See SSE_SERVER_SETUP.md for detailed instructions on:

• Reverse proxy configuration (nginx/caddy)

• SSL certificate setup

• Process management (PM2, systemd)

• Firewall and security considerations

5. Test server (no credentials required):

For testing the SSE connection without NowCerts credentials:

Then connect to http://localhost:3000/sse from Claude Desktop.

Available Tools

The server provides 96+ tools organized by category:

Agent Management (1 tool)

• nowcerts_agent_getList - Retrieve agents with search and pagination

Insured Management (6 tools)

• nowcerts_insured_getList - Get paginated insureds list

• nowcerts_insured_getInsureds - Get insureds via Zapier endpoint

• nowcerts_insured_insert - Insert new insured

• nowcerts_insured_insertNoOverride - Insert without overriding

• nowcerts_insured_insuredAndPoliciesInsert - Insert insured with policies

• nowcerts_insured_insertWithCustomFields - Insert with custom fields

Policy Management (4 tools)

• nowcerts_policy_getList - Get paginated policies list

• nowcerts_policy_getPolicies - Find policies with filters

• nowcerts_policy_get - Get specific policy

• nowcerts_policy_insert - Insert new policy

Quote Management (2 tools)

• nowcerts_quote_getQuotes - Retrieve quotes

• nowcerts_quote_insert - Insert new quote

Prospect Management (6 tools)

• nowcerts_prospect_getProspects - Get prospects

• nowcerts_prospect_insert - Insert new prospect

• nowcerts_prospect_insertWithCustomFields - Insert with custom fields

• nowcerts_prospect_xmlPush - Push prospects via XML

• nowcerts_prospect_quoteRequestExternalImportWithProspect - Import quote request with prospect

• nowcerts_prospect_quoteRequestExternalImport - Import external quote request

Claim Management (3 tools)

• nowcerts_claim_getList - Get paginated claims

• nowcerts_claim_getClaims - Get claims via Zapier

• nowcerts_claim_insert - Insert new claim

Note Management (2 tools)

• nowcerts_note_getNotes - Retrieve notes

• nowcerts_note_insert - Insert new note

Tag Management (2 tools)

• nowcerts_tag_getTags - Get tags

• nowcerts_tag_insert - Apply/insert tag

Driver Management (3 tools)

• nowcerts_driver_getDrivers - Get drivers

• nowcerts_driver_insert - Insert new driver

• nowcerts_driver_bulkInsert - Bulk insert drivers

Vehicle Management (3 tools)

• nowcerts_vehicle_getVehicles - Get vehicles

• nowcerts_vehicle_insert - Insert new vehicle

• nowcerts_vehicle_bulkInsert - Bulk insert vehicles

Task Management (2 tools)

• nowcerts_task_getTasks - Get tasks

• nowcerts_task_insert - Insert new task

Opportunity Management (2 tools)

• nowcerts_opportunity_getOpportunities - Get opportunities

• nowcerts_opportunity_insert - Insert new opportunity

Service Request Management (12 tools)

• nowcerts_serviceRequest_getAddDriver - Get add driver requests

• nowcerts_serviceRequest_getAddressChanges - Get address change requests

• nowcerts_serviceRequest_getRemoveDriver - Get remove driver requests

• nowcerts_serviceRequest_getReplaceDriver - Get replace driver requests

• nowcerts_serviceRequest_getVehicleTransfer - Get vehicle transfer requests

• nowcerts_serviceRequest_getGeneric - Get generic service requests

• nowcerts_serviceRequest_insertAddDriver - Insert add driver request

• nowcerts_serviceRequest_insertAddressChanges - Insert address change request

• nowcerts_serviceRequest_insertRemoveDriver - Insert remove driver request

• nowcerts_serviceRequest_insertReplaceDriver - Insert replace driver request

• nowcerts_serviceRequest_insertVehicleTransfer - Insert vehicle transfer request

• nowcerts_serviceRequest_insertGeneric - Insert generic service request

Customer Management (1 tool)

• nowcerts_customer_getCustomers - Get customers with search

Custom Panel Management (2 tools)

• nowcerts_customPanel_getStructure - Get custom panel structure

• nowcerts_customPanel_insert - Insert custom panel data

SMS Management (3 tools)

• nowcerts_sms_getSmses - Get SMS messages

• nowcerts_sms_insert - Insert/send SMS

• nowcerts_sms_twilio - Send SMS via Twilio

Principal Management (3 tools)

• nowcerts_principal_getList - Get paginated principals

• nowcerts_principal_getPrincipals - Get principals via Zapier

• nowcerts_principal_insert - Insert new principal

Property Management (3 tools)

• nowcerts_property_getProperties - Get properties

• nowcerts_property_insert - Insert new property

• nowcerts_property_insertOrUpdate - Insert or update property

Call Log Management (2 tools)

• nowcerts_callLogRecord_getCallLogRecords - Get call log records

• nowcerts_callLogRecord_insert - Insert call log record

Workers Compensation (1 tool)

• nowcerts_workersCompensation_insert - Insert workers comp data

Quote Application Management (3 tools)

• nowcerts_quoteApplication_getQuoteApplications - Get quote applications

• nowcerts_quoteApplication_push - Push quote applications

• nowcerts_quoteApplication_quoteRushPush - Push via QuoteRush

Zapier Integration (2 tools)

• nowcerts_zapier_subscribe - Subscribe to webhook

• nowcerts_zapier_unsubscribe - Unsubscribe from webhook

Third-Party Integrations (4 tools)

• nowcerts_cognito_webHook - Cognito webhook integration

• nowcerts_cloudIt_processData - CloudIt data processing

• nowcerts_nationwide_callbackUrl - Nationwide callback

• nowcerts_agencyRevolution_activities - Agency Revolution activities

External API Integrations (11 tools)

Fenris Household Data (1 tool)

Prefill household and vehicle data from Fenris database. Requires FENRIS_CLIENT_ID and FENRIS_CLIENT_SECRET.

• fenris_prefillHousehold - Get household data including vehicles, drivers, and insurance info

Features:

• OAuth 2.0 authentication with automatic token caching (70% faster after first call)

• Complete household data: name, address, drivers, vehicles, current insurance

• Token automatically renews before expiration

Smarty Address Validation (1 tool)

Validate and standardize US addresses. Requires SMARTY_AUTH_ID and SMARTY_AUTH_TOKEN.

• smarty_verifyAddress - Validate address and get standardized components

Features:

• USPS-validated addresses

• Delivery point validation

• ZIP+4 code lookup

• Address standardization

NHTSA Vehicle Data (2 tools)

Query NHTSA database for vehicle specifications and recalls. No credentials required (public API).

• nhtsa_decodeVin - Decode VIN to get vehicle specifications

• nhtsa_checkRecalls - Get safety recalls for specific VIN

Features:

• Complete vehicle specifications from VIN

• Safety recall information

• Make, model, and year details

• No authentication required

AskKodiak Commercial Insurance (6 tools)

Commercial insurance risk classification and carrier eligibility. Requires ASKKODIAK_GROUP_ID and ASKKODIAK_API_KEY.

• askkodiak_classifyBusiness - Search for NAICS codes by business description or decode specific NAICS code

• askkodiak_getEligibleCarriers - Find insurance carriers/products for a business type (NAICS code)

• askkodiak_getCarriers - Get list of all available insurance carriers/companies

• askkodiak_getCarrierProducts - Get all products offered by a specific carrier

• askkodiak_getApplicationQuestions - Get application questions for a specific insurance product

• askkodiak_getUnderwritingRules - Get underwriting rules and guidelines for a product

Features:

• NAICS code classification for commercial risks

• Carrier appetite and eligibility determination

• Dynamic quote application questions (replaces static ACORD forms)

• Underwriting rules and guidelines

• Automated carrier selection based on business type

• Supports General Liability, BOP, Workers Comp, and all commercial lines

Typical Workflow:

1. Use askkodiak_classifyBusiness to get NAICS code from business description (e.g., "bakery" → NAICS 311811)

2. Use askkodiak_getEligibleCarriers to find which carriers write that business class

3. Use askkodiak_getApplicationQuestions to get product-specific application questions

4. Use askkodiak_getUnderwritingRules to pre-screen the risk before submission

5. Collect answers from customer and submit to carrier

Benefits:

• Replaces manual carrier appetite guides with real-time eligibility data

• Ensures correct business classification for accurate quoting

• Reduces application errors with structured, dynamic questionnaires

• Improves quote hit ratio by pre-screening risks against underwriting rules

Usage Examples

Once configured in Claude Desktop, you can use natural language to interact with NowCerts:

Example 1: Get Insureds

Claude will use the nowcerts_insured_getList tool with appropriate filters.

Example 2: Create a New Prospect

Claude will use the nowcerts_prospect_insert tool with the provided data.

Example 3: Search Policies

Claude will use the nowcerts_policy_getList tool with date filters.

AI Assistant Integrations

VAPI Voice AI (Phone Calls)

Create voice AI assistants that can handle insurance quotes over the phone:

The voice assistant will:

• Answer inbound calls with natural conversation

• Gather customer information one question at a time

• Use Fenris to auto-discover vehicles at the address

• Provide multi-carrier insurance quotes

• Handle call transfers and appointment booking

Full Documentation: docs/VAPI_INTEGRATION.md

System Prompts:

• prompts/VAPI_SYSTEM_PROMPT.md - Voice conversation guidelines

• prompts/VAPI_AGENCY_CONTEXT.md - Agency-specific configuration

Examples: examples/VAPI_EXAMPLE_CALLS.md

N8N Automation (Chat/SMS/Email)

Use the system prompts in your N8N workflows for text-based conversations:

System Prompts:

• prompts/N8N_SYSTEM_PROMPT.md - Chat/SMS/Email guidelines

• prompts/N8N_QUICK_REFERENCE.md - Quick reference

Examples: examples/N8N_EXAMPLE_CONVERSATION.md

Key differences from voice:

• Can show lists and formatting

• Users can scroll back through conversation

• Links and images are supported

• Responses can be longer

Connecting to the MCP Server

All AI assistants (VAPI, N8N, Claude Desktop) connect to the same MCP server:

Production URL: https://mcp.srv992249.hstgr.cloud/sse

For VAPI assistants:

For N8N workflows: Use the MCP connector node (or custom HTTP requests to the MCP server)

For Claude Desktop: Add to claude_desktop_config.json (see Configuration section above)

Development

Build

Watch Mode (for development)

Run Directly

Architecture

The MCP server is built with:

• @modelcontextprotocol/sdk: Core MCP protocol implementation

• axios: HTTP client for API requests

• TypeScript: Type-safe implementation

Key Components

1. NowCertsClient: Handles OAuth authentication and API requests

2. Tool Definitions: 96+ tool schemas defining inputs and outputs

3. Endpoint Mapping: Maps tool names to API endpoints

4. Server Handler: Processes tool requests and returns results

Authentication Flow

1. Server reads credentials from environment variables

2. On first request, authenticates using OAuth password grant

3. Stores access token and refresh token

4. Automatically refreshes token when expired

5. Retries failed requests after token refresh

Error Handling

The server provides detailed error messages including:

• Authentication failures

• API errors with response data

• Network issues

• Invalid tool parameters

API Coverage

This server provides complete coverage of the NowCerts API plus external integrations:

• 100+ NowCerts endpoints: Full coverage of insurance management platform

• 6 External API tools: Fenris household data, Smarty validation, NHTSA vehicle data

• 25+ entity types: Agents, Insureds, Policies, Claims, Prospects, Drivers, Vehicles, etc.

• Full CRUD operations: Create, Read, Update, Delete across all entity types

• Advanced features: Search, filtering, pagination, custom fields

• Third-party integrations: Cognito, CloudIt, Nationwide, Agency Revolution

• Smart caching: OAuth token caching for 70% faster external API calls

License

MIT

Support

For issues related to:

• MCP Server: Open an issue in this repository

• NowCerts API: Contact NowCerts support

• Claude Desktop: Visit Anthropic's documentation

Related

• NowCerts PHP SDK - The underlying PHP SDK

• Model Context Protocol - MCP specification

• Claude Desktop - AI assistant with MCP support