MCP Server for Claude Code

Calculate U.S. surplus lines taxes directly in Claude Code without leaving your development environment. Our MCP (Model Context Protocol) server brings the full power of the Surplus Lines Tax API to your AI assistant.

Why Use the MCP Server?

• Stay in Flow — Calculate taxes without switching to a browser or separate tool
• Natural Language — Just ask Claude: "What's the SL tax on a $50,000 premium in Texas?"
• Full API Access — All 50 states + DC + territories, all coverage types
• Instant Results — Get detailed breakdowns in seconds
• Developer Friendly — Perfect for insurance software development

Prerequisites

Before installing the MCP server, ensure you have:

1. Node.js 18+

   The MCP server requires Node.js 18 or later. Check your version:

   node --version

2. Claude Code or Claude Desktop

   You need Claude Code (CLI) or Claude Desktop with MCP support enabled.

3. API Key

   Get your API key at app.surpluslinesapi.com. New accounts include 100 free queries.

How It Works

The MCP server acts as a bridge between Claude and the Surplus Lines Tax API:

Installation

Install the MCP server via npm:

# Install globally (recommended)
npm install -g surplus-lines-tax-mcp

# Or install locally in your project
npm install surplus-lines-tax-mcp

The package is available on npm at npmjs.com/package/surplus-lines-tax-mcp

surplus-lines-tax-mcp --help

Configuration

Add the MCP server to your Claude Code or Claude Desktop configuration.

Option 1: User Settings (All Projects)

Edit ~/.claude/settings.json to enable the server globally:

{
  "mcpServers": {
    "surplus-lines-tax": {
      "command": "npx",
      "args": ["surplus-lines-tax-mcp"],
      "env": {
        "SLAPI_API_KEY": "your-api-key-here"
      }
    }
  }
}

Option 2: Project Settings (Specific Project)

Create .claude/settings.local.json in your project root:

{
  "mcpServers": {
    "surplus-lines-tax": {
      "command": "npx",
      "args": ["surplus-lines-tax-mcp"],
      "env": {
        "SLAPI_API_KEY": "your-api-key-here"
      }
    }
  }
}

Claude Desktop Configuration

For Claude Desktop on macOS, edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "surplus-lines-tax": {
      "command": "npx",
      "args": ["surplus-lines-tax-mcp"],
      "env": {
        "SLAPI_API_KEY": "your-api-key-here"
      }
    }
  }
}

Testing the Server

Verify your installation works by running the server directly:

Quick Test

# Test that the server starts (Ctrl+C to exit)
SLAPI_API_KEY="your-api-key" npx surplus-lines-tax-mcp

If configured correctly, the server will start and wait for MCP connections. Press Ctrl+C to exit.

Test with Claude Code

After configuring your settings, restart Claude Code and ask:

"Calculate the surplus lines tax for a $10,000 premium in Texas"

Expected response: Claude will return the tax calculation with state tax ($485), stamping fee ($18), and grand total ($10,503).

Tool: calculate_surplus_lines_tax

The main calculation tool. Returns detailed tax breakdowns for any state and premium amount.

Parameters

Example Response

{
  "state": "Texas",
  "premium": 10000,
  "sl_tax": 485,
  "tax_rate": 0.0485,
  "stamping_fee": 18,
  "stamping_fee_rate": 0.0018,
  "total_taxes_and_fees": 503,
  "grand_total": 10503
}

Tool: list_supported_states

Returns a list of all supported U.S. states and territories for tax calculations.

Parameters

None required.

Returns

Array of all 50 states plus:

• District of Columbia
• Puerto Rico
• U.S. Virgin Islands

Tool: get_state_tax_info

Get current tax rate information for a specific state without performing a calculation.

Parameters

Returns

Current tax rates including:

• Surplus lines tax rate
• Stamping fee rate (if applicable)
• Filing fee rate (if applicable)
• Special rules and notes

Usage Examples

Once configured, just ask Claude naturally:

Troubleshooting

"SLAPI_API_KEY environment variable is required"

Your API key is not configured. Make sure the env section in your settings includes your API key:

"env": {
  "SLAPI_API_KEY": "your-actual-api-key"
}

"API error (401)"

Your API key is invalid or expired. Verify your key at app.surpluslinesapi.com.

"API error (402)"

Your account balance is depleted. Add funds at app.surpluslinesapi.com.

MCP Server Not Appearing in Claude

• Restart Claude Code or Claude Desktop after editing settings
• Verify the package is installed: npx surplus-lines-tax-mcp --help
• Check that Node.js 18+ is installed and in your PATH
• Try running manually: SLAPI_API_KEY="your-key" npx surplus-lines-tax-mcp

Getting Help

Contact us at support@undtec.com for assistance.

Pricing

MCP server usage follows the same pricing as the REST API:

Get Your API Key View Full Documentation