Smarty MCP Server

TL;DR: The Smarty MCP server lets AI assistants and other MCP-compatible clients verify, enrich, and geocode addresses using the same Smarty APIs you already rely on — all through the open Model Context Protocol.

The server exposes 20 tools spanning US address verification, international address verification, ZIP Code lookup, reverse geocoding, property enrichment, census geographic data, secondary address data, and business data. Each tool maps directly to an underlying Smarty API, so you get the same data quality and coverage available through Smarty's REST APIs.

Before you begin

• Get your Smarty credentials. You'll need an Auth ID and Auth Token (secret key). See Account Authentication for details.
• Check your subscription. Each tool maps to a Smarty API. Your subscription must include a license for that API, or calls will be rejected upstream. See pricing or contact Smarty Sales.
• Pick your MCP client. See Getting started for copy-paste setup instructions for Claude Code, Claude Desktop, Gemini, and Ollama.

Authentication & licensing

Every tool call requires Smarty API credentials to be passed as HTTP headers. These are the same auth-id and auth-token (secret key) credentials used with Smarty's REST APIs. See Smarty's Account Authentication for details on obtaining credentials.

Header	Description	Requirements
Auth-Id	Your Smarty Auth ID	Required. Max 256 characters, printable ASCII only.
Auth-Token	Your Smarty Auth Token (secret key)	Required. Max 256 characters, printable ASCII only.

Each tool maps to an underlying Smarty API. Your Smarty subscription must include a valid license for the corresponding API in order to use that tool. If your subscription doesn't cover a particular API, calls to its tools will be rejected by the upstream Smarty service. Visit smarty.com/pricing for plan details, or contact Smarty Sales to ensure your subscription covers the tools you need.

Getting started

Set up the Smarty MCP server in your AI tool of choice. Each section below provides a copy-paste configuration for a specific client.

Claude Code

Claude Code supports remote MCP servers natively over HTTP — no bridge or proxy needed.

1. Set environment variables for your Smarty credentials:

export SMARTY_AUTH_ID="your-auth-id"
export SMARTY_AUTH_TOKEN="your-auth-token"

2. Register the server:

claude mcp add smarty-addresses \
	https://mcp.api.smarty.com \
	--transport http \
	--header "Auth-Id:${SMARTY_AUTH_ID}" \
	--header "Auth-Token:${SMARTY_AUTH_TOKEN}"

Once registered, Claude Code will discover the Smarty address tools automatically. You can verify with claude mcp list.

Claude Desktop

Claude Desktop doesn't natively support remote HTTP MCP servers. Use the mcp-remote package as a stdio-to-HTTP bridge. This requires Node.js to be installed.

Add the following to your claude_desktop_config.json:

{
	"mcpServers": {
		"smarty": {
			"command": "npx",
			"args": [
				"-y",
				"mcp-remote@latest",
				"https://mcp.api.smarty.com/",
				"--header",
				"Auth-Id:YOUR_SMARTY_AUTH_ID",
				"--header",
				"Auth-Token:YOUR_SMARTY_AUTH_TOKEN"
			]
		}
	}
}

Gemini

Gemini supports MCP servers through its tool configuration. Add the Smarty MCP server to your Gemini settings:

{
	"mcpServers": {
		"smarty": {
			"url": "https://mcp.api.smarty.com/",
			"headers": {
				"Auth-Id": "YOUR_SMARTY_AUTH_ID",
				"Auth-Token": "YOUR_SMARTY_AUTH_TOKEN"
			}
		}
	}
}

Gemini will discover the available tools via the MCP protocol and can call them as part of its responses.

Ollama (via Open WebUI)

Ollama itself doesn't natively support MCP, but you can connect it through Open WebUI, which adds MCP support for locally running models.

1. Install and start Open WebUI (see the Open WebUI documentation for setup instructions).
2. In the Open WebUI admin panel, go to Settings → Tools → MCP Servers and add a new server with the following configuration:

   {
   	"smarty": {
   		"url": "https://mcp.api.smarty.com/",
   		"headers": {
   			"Auth-Id": "YOUR_SMARTY_AUTH_ID",
   			"Auth-Token": "YOUR_SMARTY_AUTH_TOKEN"
   		}
   	}
   }

3. Select an Ollama model that supports tool use (e.g., llama3.1, mistral, qwen2.5).
4. The Smarty address tools will be available to the model during conversations through Open WebUI's tool-calling interface.

Other MCP clients

Any MCP-compatible client can connect to the server. Point the client at https://mcp.api.smarty.com/ and include your Smarty credentials as HTTP headers (Auth-Id and Auth-Token). The client will discover available tools automatically via the tools/list method.

Available tools

The server exposes 20 tools organized into US address verification, enrichment, geographic data, business data, international address verification, and international postal codes. Here is a brief description of each tool. For more detailed information, continue reading below the table.

Tool name	Category	Description
US_Address	US verification	Validate a single US address
US_Address_Bulk	US verification	Validate up to 1,000 US addresses at once
US_ZIP_Code	US verification	Look up city/state/ZIP combinations
US_Reverse_Geo	US verification	Find addresses by latitude/longitude
US_Address_Enrichment_Smartykey	Enrichment	Property & financial data by SmartyKey®
US_Address_Enrichment_Components	Enrichment	Property & financial data by address
US_Geo_Data_2010_Smartykey	Geographic	2010 census geo data by SmartyKey
US_Geo_Data_2010_Components	Geographic	2010 census geo data by address
US_Geo_Data_2020_Smartykey	Geographic	2020 census geo data by SmartyKey
US_Geo_Data_2020_Components	Geographic	2020 census geo data by address
US_Secondary_data_Smartykey	Enrichment	All secondary addresses by SmartyKey
US_Secondary_data_Components	Enrichment	All secondary addresses by address
US_Secondary_Count_Smartykey	Enrichment	Secondary address count by SmartyKey
US_Secondary_Count_Components	Enrichment	Secondary address count by address
US_Business_Summary_Smartykey	Business	List of businesses at an address by SmartyKey
US_Business_Summary_Components	Business	List of businesses at an address by components
US_Business_Detail	Business	Detailed business information by business_id
International_Addresses	International	Verify a single international address
International_Addresses_Bulk	International	Verify up to 100 international addresses
International_Address_PostalCode	International	Look up international postal codes

US_Address

Validate a single US address and return structured, USPS-verified results. Uses the US Street Address API with an enhanced match strategy. Returns up to 1 candidate result per lookup.

Response fields match the US Street Address API output. See the API reference for field definitions, DPV match codes, footnotes, and interpretation guidance.

Input fields

Field	Type	Description
address (required)	string	The address to validate (freeform).
project_us_at_format	boolean	Set to true to return results in Project US@ format.
county_source	boolean	Set to true to return county information based on the physical location of the address.
component_analysis	boolean	Set to true to return detailed component analysis of the address. Reveals whether a component is confirmed, unconfirmed, or missing, what was changed, and why. Requires a subscription that includes Component Analysis.
iana_timezone	boolean	Set to true to return IANA-standard timezone fields (iana_time_zone, iana_utc_offset, iana_dst) in place of the default time_zone, utc_offset, and dst fields.

Example

{
	"jsonrpc": "2.0",
	"id": 1,
	"method": "tools/call",
	"params": {
		"name": "US_Address",
		"arguments": {
			"address": "1 Rosedale St, Baltimore, MD"
		}
	}
}

US_Address_Bulk

Validate multiple US addresses in a single call. Accepts up to 1,000 freeform address strings. Uses the US Street Address API. Addresses are processed in batches internally for efficiency. Each address uses the enhanced match strategy with 1 candidate per address. Results include input_index and input_address for correlation.

Response fields match the US Street Address API output. See the API reference for field definitions, DPV match codes, footnotes, and interpretation guidance.

Input fields

Field	Type	Description
addresses (required)	array<string>	The addresses to validate. Min 1, max 1,000. Each address may not exceed 512 characters.
lookup_count (required)	integer	The number of addresses being sent. Must match the length of the addresses array.
user_approved (required)	boolean	Must be true, indicating the user has explicitly approved the lookup count. The AI assistant must tell the user the exact number of lookups and receive confirmation before setting this to true.

Example

{
	"jsonrpc": "2.0",
	"id": 2,
	"method": "tools/call",
	"params": {
		"name": "US_Address_Bulk",
		"arguments": {
			"addresses": [
				"1 Rosedale St, Baltimore, MD",
				"1600 Amphitheatre Pkwy, Mountain View, CA"
			],
			"lookup_count": 2,
			"user_approved": true
		}
	}
}

US_ZIP_Code

Look up city/state/ZIP Code combinations. Smarty returns valid matches for any combination of city, state, and zipcode. Uses the US ZIP Code API.

Response fields match the US ZIP Code API output. See the API reference for field definitions.

Input fields

Field	Type	Description
city	string	City name.
state	string	State name or two-letter abbreviation.
zipcode	string	ZIP Code.

Example

{
	"jsonrpc": "2.0",
	"id": 3,
	"method": "tools/call",
	"params": {
		"name": "US_ZIP_Code",
		"arguments": {
			"city": "Provo",
			"state": "UT"
		}
	}
}

US_Reverse_Geo

Find addresses near a geographic coordinate. Uses the US Reverse Geocoding API. Returns an empty result message if no addresses are found near the given coordinates.

Response fields match the US Reverse Geocoding API output. See the API reference for field definitions.

Input fields

Field	Type	Description
latitude (required)	number	The latitude coordinate.
longitude (required)	number	The longitude coordinate.

Example

{
	"jsonrpc": "2.0",
	"id": 4,
	"method": "tools/call",
	"params": {
		"name": "US_Reverse_Geo",
		"arguments": {
			"latitude": 40.2335,
			"longitude": -111.6586
		}
	}
}

Enrichment tools

The enrichment tools use the US Address Enrichment API to return property, financial, geographic, and secondary address data. Response fields match the US Address Enrichment API output. See the API reference for field definitions, attribute groups, and dataset details.

Each enrichment tool comes in two variants:

• By SmartyKey — Pass a smarty_key obtained from a prior US_Address lookup.
• By components — Pass the address directly via freeform or individual components (street, city, state, zipcode).

Input fields

By SmartyKey

Used by: US_Address_Enrichment_Smartykey, US_Geo_Data_2010_Smartykey, US_Geo_Data_2020_Smartykey, US_Secondary_data_Smartykey, US_Secondary_Count_Smartykey

Field	Type	Description
smarty_key (required)	string	The SmartyKey identifier for the address.
features	string	Features to include. Present in the schema for all SmartyKey enrichment tools. Defaults to "financial" for US_Address_Enrichment_Smartykey when not provided.
etag	string	ETag from a previous response for conditional requests.

By address components

Used by: US_Address_Enrichment_Components, US_Geo_Data_2010_Components, US_Geo_Data_2020_Components, US_Secondary_data_Components, US_Secondary_Count_Components

Field	Type	Description
freeform	string	The entire address as a single string.
street	string	Street address line.
city	string	City name.
state	string	State name or abbreviation.
zipcode	string	ZIP Code.
features	string	Features to include. Present in the schema for all Components enrichment tools. Defaults to "financial" for US_Address_Enrichment_Components when not provided.
etag	string	ETag from a previous response for conditional requests.

Provide either freeform or a combination of street, city, state, and zipcode.

US_Address_Enrichment_Smartykey

Retrieve detailed enrichment and financial information for an address using its SmartyKey. Uses the Property Principal lookup. If features isn't provided, defaults to "financial". Supports conditional requests via ETag — returns {"etag": "...", "not_modified": true} when data is unchanged.

US_Address_Enrichment_Components

Same as US_Address_Enrichment_Smartykey, but accepts address components or freeform input instead of requiring a SmartyKey.

US_Geo_Data_2010_Smartykey / US_Geo_Data_2010_Components

Retrieve 2010 census geographic reference data for an address. Returns census tract, block, FIPS Codes, and other 2010 census geographic data.

US_Geo_Data_2020_Smartykey / US_Geo_Data_2020_Components

Retrieve 2020 census geographic reference data for an address. Returns census tract, block, FIPS Codes, and other 2020 census geographic data.

US_Secondary_data_Smartykey / US_Secondary_data_Components

Retrieve all secondary (unit-level) addresses associated with a root address. Returns apartment, suite, and unit numbers, if applicable — useful for identifying multi-unit buildings.

US_Secondary_Count_Smartykey / US_Secondary_Count_Components

Retrieve the total number of secondary addresses associated with a root address, without additional surrounding metadata on each one. A lighter-weight alternative when only the count is needed.

Enrichment examples

By SmartyKey (obtained from a prior US_Address call):

{
	"jsonrpc": "2.0",
	"id": 5,
	"method": "tools/call",
	"params": {
		"name": "US_Address_Enrichment_Smartykey",
		"arguments": {
			"smarty_key": "1234567890"
		}
	}
}

By address components:

{
	"jsonrpc": "2.0",
	"id": 6,
	"method": "tools/call",
	"params": {
		"name": "US_Address_Enrichment_Components",
		"arguments": {
			"freeform": "1 Rosedale St, Baltimore, MD 21229"
		}
	}
}

Business data tools

The business data tools return information about businesses located at a given US address. Use the two-step flow: call a US_Business_Summary_* tool to get a list of businesses (each with a business_id), then call US_Business_Detail with a business_id to retrieve detailed information for a specific business. These tools use the US Address Enrichment API business datasets. See the API reference for field definitions.

US_Business_Summary_Smartykey

Retrieve a list of businesses at an address using its SmartyKey. Returns company names and business_id values for use with US_Business_Detail.

Input fields

Field	Type	Description
smarty_key (required)	string	The SmartyKey identifier for the address, obtained from a prior US_Address or US_Address_Bulk call.
etag	string	ETag from a previous response for conditional requests.

US_Business_Summary_Components

Same as US_Business_Summary_Smartykey but accepts address components or freeform input instead of requiring a SmartyKey. Provide either freeform or a combination of street, city, state, and zipcode.

Input fields

Field	Type	Description
freeform	string	The entire address as a single string (e.g., "1600 Pennsylvania Ave Washington DC 20500").
street	string	Street line including house number.
city	string	City name.
state	string	Two-letter state abbreviation.
zipcode	string	5-digit or ZIP+4 postal code.
etag	string	ETag from a previous response for conditional requests.

US_Business_Detail

Retrieve detailed business information for a single business. Accepts only a business_id obtained from a prior US_Business_Summary_Smartykey or US_Business_Summary_Components call — do not pass a smarty_key or address fields.

Input fields

Field	Type	Description
business_id (required)	string	The business_id from a Business Summary response.
etag	string	ETag from a previous response for conditional requests.

Business examples

Summary by SmartyKey (obtained from a prior US_Address call):

{
	"jsonrpc": "2.0",
	"id": 10,
	"method": "tools/call",
	"params": {
		"name": "US_Business_Summary_Smartykey",
		"arguments": {
			"smarty_key": "1234567890"
		}
	}
}

Summary by address components:

{
	"jsonrpc": "2.0",
	"id": 11,
	"method": "tools/call",
	"params": {
		"name": "US_Business_Summary_Components",
		"arguments": {
			"freeform": "1600 Pennsylvania Ave Washington DC 20500"
		}
	}
}

Detail by business_id (obtained from a prior Business Summary call):

{
	"jsonrpc": "2.0",
	"id": 12,
	"method": "tools/call",
	"params": {
		"name": "US_Business_Detail",
		"arguments": {
			"business_id": "BIZ-ABC123"
		}
	}
}

International_Addresses

Verify a single international address using the International Street Address API. Provide either freeform (plus country) or individual component fields.

Response fields match the International Street Address API output. See the API reference for field definitions.

Input fields

Field	Type	Description
country (required)	string	Country name or ISO classification (ISO-3, ISO-2, or ISO-N). Examples: "France", "FRA", "FR", "250".
freeform	string	Entire address in a single field (without country). If specified, other address fields (except country) are ignored.
address1	string	First address line.
address2	string	Second address line.
address3	string	Third address line.
address4	string	Fourth address line.
organization	string	Name of the recipient, firm, or company.
locality	string	City name.
administrative_area	string	State or province name or abbreviation.
postal_code	string	Postal code.
geocode	boolean	Set to true to enable geocoding (disabled by default).
language	string	Output language: "native" (country's local language) or "latin" (Latin/ASCII). Supported: Cyrillic (Russia), Greek (Greece), Hebrew (Israel), Kanji (Japan), Simplified Chinese (China), Arabic (UAE), Thai (Thailand), Hangul (South Korea).
features	string	A comma-separated list of features to include. Valid values: "occupant-use", "geocode-classification", "geocode-precision-enhanced".

Example

{
	"jsonrpc": "2.0",
	"id": 7,
	"method": "tools/call",
	"params": {
		"name": "International_Addresses",
		"arguments": {
			"country": "France",
			"freeform": "1 Rue de Rivoli, 75001 Paris"
		}
	}
}

International_Addresses_Bulk

Verify multiple international addresses in a single call. Uses the International Street Address API. Accepts up to 100 address objects, each with the same fields as International_Addresses. In bulk, the features field supports only "occupant-use". Results include input_index and input_address for correlation.

Response fields match the International Street Address API output. See the API reference for field definitions.

Input fields

Field	Type	Description
addresses (required)	array<object>	Array of address objects. Each object accepts the same fields as International_Addresses. Min 1, max 100. Each string field may not exceed 512 characters.
lookup_count (required)	integer	The number of addresses being sent. Must match the length of the addresses array.
user_approved (required)	boolean	Must be true, indicating the user has explicitly approved the lookup count. The AI assistant must tell the user the exact number of lookups and receive confirmation before setting this to true.

Example

{
	"jsonrpc": "2.0",
	"id": 8,
	"method": "tools/call",
	"params": {
		"name": "International_Addresses_Bulk",
		"arguments": {
			"addresses": [
				{
					"country": "Canada",
					"freeform": "263 Queen St W, Toronto, ON M5V 1Z4"
				},
				{
					"country": "Australia",
					"address1": "1 George St",
					"locality": "Sydney",
					"administrative_area": "NSW",
					"postal_code": "2000"
				}
			],
			"lookup_count": 2,
			"user_approved": true
		}
	}
}

International_Address_PostalCode

Look up postal codes for cities or countries worldwide using the International Postal Code API. You may submit a postal code prefix to widen your search.

Response fields match the International Postal Code API output. See the API reference for field definitions.

Input fields

Field	Type	Description
country (required)	string	Country name or ISO classification (ISO-3, ISO-2, or ISO-N). Examples: "Brazil", "BRA", "BR", "076".
postal_code (required)	string	The postal code (e.g., "T4B 5M7"). Submit a prefix to widen results (e.g., "T4B 5").
locality	string	City name (e.g., "Paris").
administrative_area	string	State or province (e.g., "Alberta" or "AB").

Example

{
	"jsonrpc": "2.0",
	"id": 9,
	"method": "tools/call",
	"params": {
		"name": "International_Address_PostalCode",
		"arguments": {
			"country": "CA",
			"postal_code": "T4B"
		}
	}
}

Protocol & transport

The server implements the MCP StreamableHTTP transport. Clients communicate by sending JSON-RPC 2.0 requests over HTTP to the root endpoint (/).

Field	Value
Server name	Smarty_Accurate_Addresses
Transport	StreamableHTTP

HTTP endpoints

Path	Method	Description
/	POST	MCP protocol endpoint. All tool calls are sent here as JSON-RPC 2.0 requests.
/	GET	SSE stream endpoint. Used by clients to receive server-sent events.
/	DELETE	Session termination. Clients send DELETE to close an MCP session.
/health	GET	Health check. Returns {"status":"ok"} with HTTP 200.

Server limits

Rate limiting

The server enforces rate limiting at two levels using token bucket algorithms: global rate limits and per-client rate limits.

Global rate limit

A server-wide rate limit caps total throughput across all clients, protecting against distributed floods.

When the global rate limit is exceeded, the server responds with an HTTP 503 Service Unavailable status code and includes a Retry-After header.

Per-client rate limit

Each client is independently rate-limited based on the Auth-Id header.

Requests missing the Auth-Id header are rejected with an HTTP 401 Unauthorized status code before rate limiting is applied. When the per-client rate limit is exceeded, the server responds with HTTP 429 Too Many Requests and includes a Retry-After header indicating how many seconds to wait before retrying.

Request body size

The server enforces a maximum request body size of 5 MB. Requests exceeding this limit are rejected with an HTTP 413 Request Entity Too Large response. This applies to all endpoints, including bulk tool calls.

Sessions

The server uses MCP sessions to maintain client state. Sessions are created automatically on the first request and identified by the Mcp-Session-Id response header.

When the maximum number of concurrent sessions is reached, session-creating requests are rejected with an HTTP 503 Service Unavailable response and a Retry-After: 30 header. Existing sessions continue to work normally. Inactive sessions automatically expire after the timeout period.

Session termination

To end a session, send an HTTP DELETE to / with the Mcp-Session-Id header. The server responds with 204 No Content.

The server may also end sessions on its own — for example, after a period of inactivity. When this happens, clients won't receive a notification unless they have an open SSE stream (via GET /). Otherwise, the client will find out the session is gone when its next request returns 404 Not Found.

If you receive a 404 on any request, treat it as an expired session and start a new one by repeating the initialization handshake.

Making raw HTTP requests

The MCP protocol requires a session initialization handshake before tool calls. The three-step flow is: initialize → notifications/initialized → tools/call.

Step 1 — Initialize the session

Send the initialize request and capture the Mcp-Session-Id header from the response.

curl -si -X POST https://mcp.api.smarty.com/ \
	-H "Content-Type: application/json" \
	-H "Auth-Id: YOUR_AUTH_ID" \
	-H "Auth-Token: YOUR_AUTH_TOKEN" \
	-d '{
		"jsonrpc": "2.0",
		"id": 1,
		"method": "initialize",
		"params": {
			"protocolVersion": "2025-06-18",
			"capabilities": {},
			"clientInfo": { "name": "example", "version": "1.0.0" }
		}
	}'

The response will include an Mcp-Session-Id header. Include this header in all subsequent requests.

Step 2 — Send the initialized notification

curl -X POST https://mcp.api.smarty.com/ \
	-H "Content-Type: application/json" \
	-H "Mcp-Session-Id: SESSION_ID_FROM_STEP_1" \
	-H "Auth-Id: YOUR_AUTH_ID" \
	-H "Auth-Token: YOUR_AUTH_TOKEN" \
	-d '{
		"jsonrpc": "2.0",
		"method": "notifications/initialized"
	}'

Step 3 — Call a tool

curl -X POST https://mcp.api.smarty.com/ \
	-H "Content-Type: application/json" \
	-H "Mcp-Session-Id: SESSION_ID_FROM_STEP_1" \
	-H "Auth-Id: YOUR_AUTH_ID" \
	-H "Auth-Token: YOUR_AUTH_TOKEN" \
	-d '{
		"jsonrpc": "2.0",
		"id": 2,
		"method": "tools/call",
		"params": {
			"name": "US_Address",
			"arguments": {
				"address": "1 Rosedale St, Baltimore, MD"
			}
		}
	}'

Error handling

Errors are returned at two levels: HTTP status codes (from server middleware) and JSON-RPC error codes (from tool execution).

HTTP errors

These are returned as standard HTTP responses before the request reaches the MCP protocol layer.

Status	Meaning	Common causes
401	Unauthorized	Missing Auth-Id header.
402	Payment Required	No active Smarty subscription for the requested API. Check your subscription.
413	Request Entity Too Large	Request body exceeds the 5 MB limit.
422	Unprocessable Entity	Request is missing a required field (e.g., no address provided).
429	Too Many Requests	Per-client rate limit exceeded. Check the Retry-After response header.
503	Service Unavailable	Global rate limit exceeded or maximum concurrent sessions reached. Check the Retry-After response header.

JSON-RPC errors

These are returned inside the JSON-RPC response error field after the request has been accepted at the HTTP level.

Code	Meaning	Common causes
-32600	Invalid Request	Missing or invalid Auth-Id / Auth-Token headers (checked at the MCP auth layer).
-32602	Invalid Params	Empty address array in bulk tools. Address count exceeds maximum (1,000 for US, 100 for international). Individual field exceeds 512 characters. lookup_count doesn't match the number of addresses. user_approved isn't true.

When a tool call returns no results (e.g., no addresses found near the given coordinates), the server returns a successful response with an empty result message rather than an error.