Ziptax Sales Tax API README

Ziptax MCP Server

An HTTP Model Context Protocol (MCP) server that gives AI agents real-time US and Canadian sales and use tax rates from the Ziptax API.

Once connected, an agent can:

• Look up sales and use tax rates by street address, latitude/longitude, or postal code.
• Get jurisdiction-level breakdowns (state, county, city, and district).
• Check account usage and quota.

Official documentation: docs.zip.tax: MCP Server

Connection Details

Authentication

Send a Ziptax API key as an HTTP header. Two header methods are supported:

X-API-KEY: your-api-key

Authorization: Bearer your-api-key

• X-API-KEY is recommended. If both headers are present, X-API-KEY takes priority.
• The Bearer scheme is case-insensitive.
• Do not pass API keys in the URL. Keys in URLs can end up in logs.

Get an API key at platform.zip.tax.

Client Configuration

Replace your_api_key with your Ziptax API key.

Claude Code

claude mcp add --transport http ziptax https://mcp.zip-tax.com/ --header "X-API-KEY: your_api_key"

Claude Desktop

Add this block to claude_desktop_config.json:

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

Cursor

Go to Settings → MCP and add a server:

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

Devin

Add the Ziptax integration from the MCP Marketplace, or configure it under Settings → MCP Marketplace → Add Your Own:

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

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

Any Other MCP Client

Any client that supports the Streamable HTTP transport can connect:

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

Example Prompts

• "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 do I have left on my Ziptax plan this month?"

Tools

The server exposes two read-only tools.

lookup_tax_rate

Look up sales and use tax rates for a US or Canadian location. Returns rates broken down by jurisdiction (state, county, city, district).

Location Requirement

Provide one of:

• address: a full street address, for door-level precision. This is the preferred input.
• lat and lng: a geographic point, with the same door-level precision as an address.

The input schema declares this as an anyOf constraint. postalcode is the least precise location input; see its description below.

Parameters

All parameters are optional, subject to the location requirement above, and the schema declares each one as a string. lat, lng, historical, and sat_item_total also accept JSON numbers. Every other parameter must be a string. For example, send postalcode as "02134", because a number drops the leading zero.

Example Call

{
  "name": "lookup_tax_rate",
  "arguments": {
    "address": "200 Spectrum Center Dr, Irvine, CA 92618"
  }
}

Response

The tool returns the Ziptax API v60 response as pretty-printed JSON text, or as the API's XML unchanged when format is xml. It mirrors the REST API by Address 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.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
  }
}

metadata.response.code reports the API response code. See Response Codes for the full list.

get_account_metrics

Get usage metrics and quota information for the authenticated Ziptax account. Takes no parameters.

Example Call

{
  "name": "get_account_metrics",
  "arguments": {}
}

Response

The tool returns the Ziptax API v60 account metrics response as pretty-printed JSON text:

{
  "request_count": 4215,
  "request_limit": 100000,
  "usage_percent": 4.215,
  "is_active": true,
  "message": "Contact support@zip.tax to modify your account"
}

See Account Metrics for details.

Error Handling

Errors come back as a tool result with isError: true and a text message, not as a JSON-RPC error.

Local Development

# Run the server
go run .

# Run tests
go test -v ./...

# Build and run the Docker image
docker build -t ziptax-mcp .
docker run -p 8080:8080 ziptax-mcp

The server listens on port 8080 by default:

• POST /: MCP endpoint
• GET /health: health check, returns {"status":"ok"}

Environment Variables

Infrastructure

The cloudformation.yaml template provisions the complete AWS infrastructure:

• ECR repository for container images
• ECS Fargate cluster and service
• Application Load Balancer with HTTPS
• ACM certificate for mcp.zip-tax.com
• Route53 hosted zone and DNS record
• Security groups and IAM roles

Deployment

CI/CD is handled by GitHub Actions:

1. test.yml - Runs on PRs and pushes: linting (golangci-lint) and tests (go test)
2. build.yml - Runs on main: builds Docker image and pushes to ECR
3. deploy.yml - Runs after build: updates the ECS service with the new image
4. pages.yml - Runs on main when this README, the LICENSE, or the workflow changes, or on manual dispatch: publishes the README as the documentation site at mcp.zip.tax

build.yml and deploy.yml authenticate to AWS by assuming an IAM role through GitHub OIDC; no workflow uses static AWS keys. The role is defined in ziptax-terraform (github_oidc.tf) and trusts only this repository's main branch. Its ARN is the AWS_DEPLOY_ROLE_ARN repository variable.

Initial Setup

1. Deploy the CloudFormation stack:

   bashCopy

   aws cloudformation deploy \
     --template-file cloudformation.yaml \
     --stack-name ziptax-mcp \
     --parameter-overrides ImageUri=<ECR_URI>:latest \
     --capabilities CAPABILITY_NAMED_IAM \
     --region us-east-1
   

2. Add NS records from the mcp.zip-tax.com hosted zone to the parent zip-tax.com zone.

3. Wait for ACM certificate DNS validation to complete.

License

MIT