Ziptax Sales Tax API

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:

   aws cloudformation deploy \

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

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

1. Wait for ACM certificate DNS validation to complete.

License

MIT