MCP Server API

TL;DR: The Smarty MCP server connects AI assistants and MCP clients to Smarty address validation, enrichment, and geocoding APIs through the open Model Context Protocol.

The server exposes 20 tools. The tools cover US address validation, international address validation, ZIP Code lookup, reverse geocoding, property enrichment, census geographic data, secondary address data, and business data. Each tool maps to one Smarty API and returns the same data quality and coverage as the Smarty REST APIs.

Before you begin

• Get your Smarty credentials. You need an Auth ID and an Auth Token (secret key). See Account Authentication.
• Check your subscription. Each tool maps to a Smarty API. Your subscription must include a license for that API, or the upstream service rejects the calls. See pricing or contact Smarty Sales.
• Pick your MCP client. See Get started for configuration steps for Claude Code, Claude Desktop, Gemini, and Ollama.

Authentication & licensing

Every tool call requires Smarty API credentials in HTTP headers. These are the same auth-id and auth-token (secret key) credentials that the Smarty REST APIs use. See Account Authentication to get credentials.

Send the credentials in one of two forms. Do not send both forms in one request.

Option 1 — Auth-Id and Auth-Token headers

Option 2 — HTTP Basic Authorization header

The initialize, notifications/initialized, and server/discover methods do not require credentials. All other methods do.

The server forwards the credentials to the Smarty API on each call. Your subscription must include a license for each API that you use. If your subscription does not include an API, the upstream Smarty service rejects calls to its tools. Visit smarty.com/pricing for plan details, or contact Smarty Sales to confirm that your subscription covers the tools that you need.

Get started

Set up the Smarty MCP server in your AI tool. Each section below gives the configuration for one client.

Claude Code

Claude Code supports remote MCP servers over HTTP. No bridge or proxy is necessary.

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}"

After registration, Claude Code discovers the Smarty tools automatically. To confirm, run claude mcp list.

Claude Desktop

Claude Desktop does not support remote HTTP MCP servers directly. Use the mcp-remote package as a stdio-to-HTTP bridge. The bridge requires Node.js.

Add this configuration 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 discovers the tools through the MCP protocol and can call them in its responses.

Ollama (via Open WebUI)

Ollama does not support MCP directly. Connect it through Open WebUI, which adds MCP support for local models.

1. Install and start Open WebUI. See the Open WebUI documentation for setup steps.

2. In the Open WebUI admin panel, go to Settings → Tools → MCP Servers. Add a new server with this 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 (for example, llama3.1, mistral, qwen2.5).
4. The model can then call the Smarty tools through the Open WebUI tool interface.

Other MCP clients

Any MCP client can connect to the server. Point the client at https://mcp.api.smarty.com/. Send your credentials as HTTP headers. The client discovers the tools through the tools/list method.

Available tools

The server exposes 20 tools in six groups: US validation, enrichment, geographic data, business data, international validation, and international postal codes. The table gives a short description of each tool. The sections below the table give full details.

US_Address

Validate one US address and return structured results from USPS reference data. The tool uses the US Street Address API. Each call costs one lookup. To validate more than one address, use US_Address_Bulk. Do not call this tool in a loop.

Send the address in one of two modes:

• Freeform — Set freeform to the full address as one string.
• Components — Set the component fields. street is required in this mode. Pair street with city and state, or with zipcode, or with lastline.

Do not combine freeform with the component fields.

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

Input fields

Match strategy

The match_strategy field controls which candidates the API returns:

• strict — Return only addresses that USPS data confirms as deliverable.
• invalid — Also return detail for addresses that fail validation.
• enhanced — Use the largest reference data set, which includes non-postal addresses such as PMBs. Default.

Examples

Freeform mode:

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

Component mode:

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

US_Address_Bulk

Validate up to 1,000 US addresses in one call. The tool uses the US Street Address API. Each element of addresses is an object with the same address fields as US_Address. One call can mix freeform elements and component elements. The server sends the addresses to the API in batches of 100. Each address returns at most one candidate. Results include input_index and input_address for correlation.

Each address costs one lookup. The tool requires the caller to state the lookup count and to confirm user approval. See the lookup_count and user_approved fields below.

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

Input fields

Example

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

US_ZIP_Code

Look up city/state/ZIP Code combinations. Set any combination of city, state, and zipcode. Smarty returns the valid matches. The tool uses the US ZIP Code API.

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

Input fields

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. The tool uses the US Reverse Geocoding API. If no addresses exist near the coordinates, the tool returns an empty result message.

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

Input fields

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 data set details.

Each enrichment tool has two variants:

• By SmartyKey — Set smarty_key to a SmartyKey from a prior US_Address lookup.
• By components — Set freeform, or set the component fields (street, city, state, zipcode). The server resolves the address internally.

All enrichment tools accept an optional etag for conditional requests. If the data is unchanged, the tool returns {"etag": "...", "not_modified": true} instead of the full result.

The Secondary, Secondary Count, Business Summary, and Business Detail tools return {"results": []} when the API has no data for the input. The US_Address_Enrichment_* and US_Geo_Data_* tools return a tool error in that case.

SmartyKey input fields

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

Components input fields

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

The Components route does not accept a smarty_key. Set at least one of freeform, street, city, state, or zipcode. (US_Business_Summary_Components adds a business-name mode — see Business data tools.)

US_Address_Enrichment_Smartykey

Retrieve enrichment and financial data for an address by its SmartyKey. The tool uses the Property Principal lookup. If features is empty, the tool applies the default financial.

US_Address_Enrichment_Components

The same as US_Address_Enrichment_Smartykey, but the input is an address instead of a SmartyKey.

US_Geo_Data_2010_Smartykey / US_Geo_Data_2010_Components

Retrieve the 2010 census geographic reference data for an address. The response includes census tract, block, and FIPS Codes, as well as other 2010 census geographic data.

US_Geo_Data_2020_Smartykey / US_Geo_Data_2020_Components

Retrieve 2020 census geographic reference data for an address. The response includes census tract, block, and FIPS Codes, as well as other 2020 census geographic data.

US_Secondary_data_Smartykey / US_Secondary_data_Components

Retrieve all secondary (unit-level) addresses for a root address. The response includes apartment, suite, and unit numbers. Use these tools to identify multi-unit buildings.

US_Secondary_Count_Smartykey / US_Secondary_Count_Components

Retrieve the number of secondary addresses for a root address, without the details of each one. Use these tools when you need only the count.

Enrichment examples

By SmartyKey (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 data about businesses at a US address. Use the two-step flow. First, call a US_Business_Summary_* tool to list the businesses, each with a business_id. Then, call US_Business_Detail with one business_id to get the full record. These tools use the US Address Enrichment API business data sets. See the API reference for field definitions.

US_Business_Summary_Smartykey

List the businesses at an address by their SmartyKey. The response includes company names and business_id values for US_Business_Detail. The input fields are the SmartyKey input fields above.

US_Business_Summary_Components

List the businesses at an address, or search for a business by name. The tool has two search modes:

• By address — Set freeform, or set the component fields (street, city, state, zipcode).
• By business name — Set business_name, plus city, state, or zipcode to narrow the search.

Do not combine business_name with freeform or street. Set at least one input field.

Input fields

US_Business_Detail

Get the full record for one business. The tool accepts only a business_id from a prior Business Summary response. It does not accept a SmartyKey or address fields.

Input fields

Business examples

Summary by SmartyKey (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 business name:

{
  "jsonrpc": "2.0",
  "id": 11,
  "method": "tools/call",
  "params": {
    "name": "US_Business_Summary_Components",
    "arguments": {
      "business_name": "Smarty",
      "city": "Provo",
      "state": "UT"
    }
  }
}

Detail by business_id (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

Validate one international address with the International Street Address API. country is required. Also set freeform or address1. If both are empty, the server returns a tool error.

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

Input fields

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

Validate up to 100 international addresses in one call. The tool uses the International Street Address API. Each element accepts the same fields as International_Addresses. The server validates the addresses one at a time. Results include input_index and input_address for correlation.

In this tool, the features field supports only "occupant-use".

Each address costs one lookup. The tool requires the caller to state the lookup count and to confirm user approval. See the lookup_count and user_approved fields below.

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

Input fields

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. The tool uses the International Postal Code API. To widen the search, send a postal code prefix.

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

Input fields

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 in stateless mode. Clients send JSON-RPC 2.0 requests over HTTP POST to the root endpoint (/).

HTTP endpoints

Request requirements

• Set Content-Type: application/json. Other content types return HTTP 415.
• Set Accept: application/json, text/event-stream. Requests without both values return HTTP 400.
• The response body is a text/event-stream stream. The JSON-RPC response is in the data: line of a message event.
• Notifications (for example, notifications/initialized) return HTTP 202 with an empty body.

Server limits

Rate limits

The server enforces two rate limits with token buckets. The per-client check runs before the global check, so a rejected client does not consume global capacity.

Per-client rate limit

The server limits each client by its Auth ID: the Auth-Id header, or the username in the Authorization: Basic header.

If a request has no Auth ID, the server rejects it with HTTP 401 Unauthorized before the limiter consumes tokens. If a client exceeds its limit, the server returns HTTP 429 Too Many Requests with a Retry-After header. The header states the wait time in seconds.

Global rate limit

A server-wide limit caps total throughput across all clients.

If requests exceed the global limit, the server returns HTTP 503 Service Unavailable with a Retry-After header.

Request body size

The maximum request body size is 5 MB. The server rejects larger requests with HTTP 413. This limit applies to all endpoints, which include bulk tool calls.

Request budget

Each tool call has a budget of 55 seconds. The budget includes retries to the Smarty API. If the budget expires, the call fails with a tool error.

Stateless operation

The server is stateless. Each request is independent and self-contained. There are no sessions to create, maintain, or terminate. The server never reads or sets the Mcp-Session-Id header. Nothing expires, and there is no concurrent-session limit.

Because there are no sessions, DELETE / returns HTTP 405 Method Not Allowed. GET / also returns 405 because the server doesn’t offer a standalone SSE stream.

Send raw HTTP requests

No handshake or session setup is necessary. One authenticated POST calls a tool directly:

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

The response arrives as a text/event-stream body. The JSON-RPC response is in the data: line:

event: message
data: {"jsonrpc":"2.0","id":1,"result":{ ... }}

Legacy clients: Clients on MCP protocol versions before 2026-07-28 send initialize and notifications/initialized before tool calls. These clients still work because the server answers each request independently. They don’t receive an Mcp-Session-Id header. They must not send GET (SSE) or DELETE requests, which return 405.

Errors

The server returns errors at three levels: HTTP status codes, JSON-RPC error codes, and tool errors.

HTTP errors

The middleware and protocol layer return these before a tool runs.

JSON-RPC errors

These come back in the JSON-RPC response error field after the HTTP layer accepts the request.

Tool errors

Failures inside a tool return a normal JSON-RPC response with isError: true in the result. Common causes: a missing tool field (for example, country is required), or an upstream Smarty API error. An upstream 402 Payment Required means that your subscription doesn’t include the API — see pricing.

Empty results

When a tool finds no data, the server returns a successful response, not an error. This applies to:

• US_Reverse_Geo — no addresses near the coordinates.
• US_Address, International_Addresses, and their _Bulk variants — no match for the address.
• The Secondary, Secondary Count, Business Summary, and Business Detail tools — the API has no data for the input.