MCP Server for AI Agents

Overview

The ZipTax MCP (Model Context Protocol) Server provides AI agents and LLM-powered applications with direct access to real-time US and Canadian sales tax rate data. MCP is an open standard that enables AI applications to securely connect to external tools and data sources.

With the ZipTax MCP Server, AI agents can:

• Look up sales and use tax rates by postal code, street address, or geographic coordinates
• Retrieve jurisdiction-level tax breakdowns (state, county, city, and district)
• Query account usage metrics and quota information

Transport

The ZipTax MCP Server uses Streamable HTTP transport. Most MCP clients refer to this as the HTTP transport type.

Prerequisites

• A valid ZipTax API key. Get one at platform.zip.tax.

Base URL

POST https://mcp.zip-tax.com

Authentication

All requests to the ZipTax MCP Server require a valid API key sent in the request.

Two request methods are supported:

Header (Recommended)

Send your API key directly in the POST Header.

EXAMPLE

X-API-KEY: your-api-key

Query Parameter (option)

Alternatively, send your API key as a url parameter key in the request URI.

EXAMPLE

?key=your-api-key

Tools

The ZipTax MCP Server exposes two tools.

lookup_tax_rate

Look up sales and use tax rates for a US or Canadian location. Provide a postal code at minimum, or a full street address for door-level precision. Returns tax rates broken down by jurisdiction (state, county, city, district).

Parameters

At least one of postalcode, address, or lat/lng is required.

Example Response

 
{
  "metadata": {
    "version": "v60",
    "response": {
      "code": 100,
      "name": "RESPONSE_CODE_SUCCESS",
      "message": "Successful API Request.",
      "definition": "http://api.zip-tax.com/request/v60/schema"
    }
  },
  "baseRates": [
    {
      "rate": 0.0725,
      "jurType": "US_STATE_SALES_TAX",
      "jurName": "CA",
      "jurDescription": "US State Sales Tax",
      "jurTaxCode": "06"
    },
    {
      "rate": 0.0725,
      "jurType": "US_STATE_USE_TAX",
      "jurName": "CA",
      "jurDescription": "US State Use Tax",
      "jurTaxCode": "06"
    },
    {
      "rate": 0.005,
      "jurType": "US_COUNTY_SALES_TAX",
      "jurName": "ORANGE",
      "jurDescription": "US County Sales Tax",
      "jurTaxCode": "30"
    },
    {
      "rate": 0.005,
      "jurType": "US_COUNTY_USE_TAX",
      "jurName": "ORANGE",
      "jurDescription": "US County Use Tax",
      "jurTaxCode": "30"
    },
    {
      "rate": 0,
      "jurType": "US_CITY_SALES_TAX",
      "jurName": "IRVINE",
      "jurDescription": "US City Sales Tax",
      "jurTaxCode": null
    },
    {
      "rate": 0,
      "jurType": "US_CITY_USE_TAX",
      "jurName": "IRVINE",
      "jurDescription": "US City Use Tax",
      "jurTaxCode": null
    }
  ],
  "service": {
    "adjustmentType": "SERVICE_TAXABLE",
    "taxable": "N",
    "description": "Services non-taxable"
  },
  "shipping": {
    "adjustmentType": "FREIGHT_TAXABLE",
    "taxable": "N",
    "description": "Freight non-taxable"
  },
  "sourcingRules": {
    "adjustmentType": "ORIGIN_DESTINATION",
    "description": "Destination Based Taxation",
    "value": "D"
  },
  "taxSummaries": [
    {
      "rate": 0.0775,
      "taxType": "SALES_TAX",
      "summaryName": "Total Base Sales Tax",
      "displayRates": [
        {
          "name": "Total Rate",
          "rate": 0.0775
        }
      ]
    },
    {
      "rate": 0.0775,
      "taxType": "USE_TAX",
      "summaryName": "Total Base Use Tax",
      "displayRates": [
        {
          "name": "Total Rate",
          "rate": 0.0775
        }
      ]
    }
  ],
  "addressDetail": {
    "normalizedAddress": "200 Spectrum Center Dr, Irvine, CA 92618-5003, United States",
    "incorporated": "true",
    "geoLat": 33.65253,
    "geoLng": -117.74794
  }
}

get_account_metrics

Retrieve account usage metrics and quota information for your ZipTax account. Returns current request counts, limits, and entitlements. This tool takes no parameters.

Client Configuration

Below are configuration examples for connecting popular MCP clients to the ZipTax MCP Server.

Devin

In Devin, add the ZipTax MCP integration from the MCP Marketplace, or configure it manually under Settings > MCP Marketplace > Add Your Own with the following configuration:

 
{
  "mcpServers": {
    "ziptax-sales-tax-api": {
      "transport": "shttp",
      "url": "https://mcp.zip-tax.com/",
      "headers": {
        "X-API-KEY": "$ZIPTAX_API_KEY"
      }
    }
  }
}

Store your API key as a secret named ZIPTAX_API_KEY in Devin's Secrets Manager.

Claude Desktop

Add the following to your Claude Desktop MCP configuration file (claude_desktop_config.json):

 
{
  "mcpServers": {
    "ziptax": {
      "type": "http",
      "url": "https://mcp.zip-tax.com/",
      "headers": {
        "X-API-KEY": "your_api_key"
      }
    }
  }
}

Cursor

In Cursor, navigate to Settings > MCP and add a new server:

• Name: Ziptax MCP Server
• Type: HTTP
• URL: https://mcp.zip-tax.com/
• Headers: X-API-KEY: your_api_key

Generic MCP Client

Any MCP client that supports the HTTP (Streamable HTTP) transport can connect to the ZipTax MCP Server.

• Name: Ziptax MCP Server
• Type: HTTP
• URL: https://mcp.zip-tax.com/
• Headers: X-API-KEY: your_api_key

Replace your_api_key with your ZipTax API key from platform.zip.tax.

Error Handling

When a request fails, the MCP Server returns an error message in the tool result. Common errors include:

For the full list of API response codes, refer to the Response Codes documentation.