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
• Automatic Fallback — Historical queries never fail, always return useful data

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

{
  "success": true,
  "state": "Texas",
  "state_code": "TX",
  "premium": 10000,
  "total_tax": 489,
  "total_due": 10489,
  "rates_from": "current",
  "breakdown": {
    "base_tax": { "rate": "4.85%", "amount": 485 },
    "stamping_fee": { "rate": "0.04%", "amount": 4 },
    "filing_fee": null,
    "service_fee": null,
    "surcharge": null,
    "regulatory_fee": null,
    "fire_marshal_tax": null,
    "slas_clearinghouse_fee": null,
    "flat_fee": null
  },
  "legislative_source": "https://statutes.capitol.texas.gov/docs/IN/htm/IN.225.htm",
  "account": {
    "balance": "0.00",
    "free_queries_remaining": 685,
    "was_free_query": true
  }
}

Tool: get_state_rate

Get tax rate information for a specific state. Supports current rates or historical rates with automatic fallback if historical data is unavailable. Each call costs $0.38.

Parameters

Example Response (Current Rate)

{
  "state": "Texas",
  "state_code": "TX",
  "tax_rate": "4.85%",
  "stamping_fee": "0.04%",
  "filing_fee": "",
  "service_fee": "",
  "surcharge": "",
  "regulatory_fee": "",
  "fire_marshal_tax": "",
  "slas_clearinghouse_fee": "",
  "flat_fee": "",
  "legislative_source": "https://statutes.capitol.texas.gov/docs/IN/htm/IN.225.htm",
  "confidence": "high",
  "data_source": "current_rate",
  "account": {
    "balance": "0.00",
    "free_queries_remaining": 684,
    "was_free_query": true
  }
}

Example Response (Historical Rate - Texas)

{
  "state": "Texas",
  "state_code": "TX",
  "tax_rate": "4.85%",
  "stamping_fee": "0.04%",
  "filing_fee": "",
  "service_fee": "",
  "surcharge": "",
  "regulatory_fee": "",
  "fire_marshal_tax": "",
  "slas_clearinghouse_fee": "",
  "flat_fee": "",
  "effective_from": "2024-01-01T00:00:00.000Z",
  "effective_to": null,
  "query_date": "2024-09-12",
  "legislative_source": "https://statutes.capitol.texas.gov/docs/IN/htm/IN.225.htm",
  "confidence": "high",
  "data_source": "initial_migration",
  "field_sources": {
    "tax_rate": "initial_migration",
    "stamping_fee": "initial_migration",
    "filing_fee": "initial_migration",
    "service_fee": "initial_migration",
    "surcharge": "initial_migration",
    "regulatory_fee": "initial_migration",
    "fire_marshal_tax": "initial_migration",
    "slas_clearinghouse_fee": "initial_migration",
    "flat_fee": "initial_migration",
    "rounding_rule": "initial_migration",
    "special_notes": "initial_migration"
  },
  "account": {
    "balance": "0.00",
    "free_queries_remaining": 683,
    "was_free_query": true
  }
}

Example Response (Automatic Fallback)

When historical data is unavailable, the API falls back to current rates. The data_source field will return "current_rate" (instead of "initial_migration") to indicate the fallback occurred. The query_date still reflects the originally requested date.

{
  "state": "Texas",
  "state_code": "TX",
  "tax_rate": "4.85%",
  "stamping_fee": "0.04%",
  "filing_fee": "",
  "service_fee": "",
  "surcharge": "",
  "regulatory_fee": "",
  "fire_marshal_tax": "",
  "slas_clearinghouse_fee": "",
  "flat_fee": "",
  "query_date": "2010-01-01",
  "legislative_source": "https://statutes.capitol.texas.gov/docs/IN/htm/IN.225.htm",
  "confidence": "high",
  "data_source": "current_rate",
  "field_sources": null,
  "account": {
    "balance": "0.00",
    "free_queries_remaining": 683,
    "was_free_query": true
  }
}

Use Cases

• Current Rates — Get today's tax rates for quote generation
• Policy Audits — Verify taxes using rates in effect at policy inception
• Renewals — Compare current vs. prior year rates
• Compliance — Document historical rate information for regulatory filings
• Rate Monitoring — Track rate changes over time (Iowa has scheduled rate reductions through 2027)

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