> This page is for version v6.0 (default).
> For other versions, use one of these documentation indexes:
> - v6.0 (default): https://docs.zip.tax/v-6-0/llms.txt
> - v5.0: https://docs.zip.tax/v-5-0/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.zip.tax/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.zip.tax/_mcp/server.

# MCP Server

The Ziptax MCP Server gives AI agents and LLM-powered applications direct
access to real-time U.S. and Canadian sales tax data. MCP is an open
standard that lets AI applications securely connect to external tools and
data sources. Once connected, your agent 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.

> **Info**
>
> You'll need a valid Ziptax API key. Create a free account at
> [platform.zip.tax](https://platform.zip.tax).

## Connection details

|               |                                                 |
| ------------- | ----------------------------------------------- |
| **Base URL**  | `https://mcp.zip-tax.com/`                      |
| **Method**    | `POST`                                          |
| **Transport** | Streamable HTTP (most clients call this `HTTP`) |

## Authentication

Every request must include a valid API key sent as an HTTP header. Two
header methods are supported.

### `X-API-KEY` header (recommended)

```http
X-API-KEY: your-api-key
```

### `Authorization` header

```http
Authorization: Bearer your-api-key
```

> **Warning**
>
> If both are present, the `X-API-KEY` header takes priority. Do not pass
> your API key as a URL parameter; keys in URLs can end up in logs.

## Tools

The server exposes two tools.

### `lookup_tax_rate`

Look up sales and use tax rates for a U.S. or Canadian location. Provide
a full street address for door-level precision, or a `lat`/`lng` pair
for a geographic point lookup. Returns tax rates broken down by
jurisdiction (state, county, city, district).

**Parameters**

Provide either `address` for a door-level lookup, or `lat` and `lng` for
a geographic point lookup. The input schema declares this requirement
as an `anyOf` constraint.

**Example response**

The tool response mirrors the Ziptax
[REST API by Address](../rest-api/by-address) response:

```json
{
  "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.005,
      "jurType": "US_COUNTY_SALES_TAX",
      "jurName": "ORANGE",
      "jurDescription": "US County Sales Tax",
      "jurTaxCode": "30"
    }
  ],
  "taxSummaries": [
    {
      "rate": 0.0775,
      "taxType": "SALES_TAX",
      "summaryName": "Total Base Sales 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. Takes
no parameters.

## Example use cases

Once connected, ask your agent things like:

* "What's the sales tax rate for ZIP code 90210?"
* "What's the combined sales tax rate at 200 Spectrum Center Dr, Irvine,
  CA?"
* "What's the sales tax rate for Canadian postal code M5V 2T6 in Toronto,
  Ontario?"
* "What was the sales tax rate in Nashville, TN (37203) in January of
  this year?"
* "How many API requests are left on my Ziptax plan this month?"

## Client configuration

Below are configuration examples for connecting popular MCP clients to the
Ziptax MCP Server. Replace `your_api_key` with your Ziptax API key from
[platform.zip.tax](https://platform.zip.tax).

### Claude Desktop

Add this block to your `claude_desktop_config.json`:

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

### Cursor

Navigate to **Settings → MCP** and add a new server with:

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

### Devin

In Devin, add the Ziptax MCP integration from the MCP Marketplace, or
configure it manually under **Settings → MCP Marketplace → Add Your Own**:

```json
{
  "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.

### Generic MCP client

Any MCP client that supports Streamable HTTP transport can connect:

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

## Error handling

When a request fails, the MCP Server returns an error message in the tool
result. For the full list of API response codes, see the
[Response Codes](../reference/response-codes) reference.