Private beta: not yet open to the public

Connect an AI agent to ListShack

Use ListShack from Claude, ChatGPT, Codex, Cursor or any MCP client: explore databases, count records for free, and buy lists with credits you approve.

Your agent connects to one URL and you sign in to ListShack in your browser. You choose the account and what the agent may do, and you can revoke it any time. You never paste an API key, password or database credential into an agent.

MCP endpoint

https://listshack.com/api/mcp

Streamable HTTP, MCP protocol versions 2025-11-25 and 2026-07-28, OAuth 2.1 Authorization Code with PKCE.

Connect your client

Each client signs in with OAuth in your browser. Clients register themselves automatically, and ListShack shows whether it recognizes the app before you approve access.

Claude Code

Add the server, then run /mcp in Claude Code and choose Authenticate.

claude mcp add --transport http listshack https://listshack.com/api/mcp

Codex CLI and app

Add the server, then sign in. Codex opens the ListShack consent page in your browser.

codex mcp add listshack --url https://listshack.com/api/mcp
codex mcp login listshack

Cursor

Add this to ~/.cursor/mcp.json (or .cursor/mcp.json in a project), then choose Connect next to ListShack in Cursor's MCP settings.

{
  "mcpServers": {
    "listshack": { "url": "https://listshack.com/api/mcp" }
  }
}

ChatGPT

Open Settings → Apps & Connectors → Create (developer mode), enter the URL below, choose OAuth, and sign in when prompted.

https://listshack.com/api/mcp

Claude.ai

Open Settings → Connectors → Add custom connector, enter the URL below, then choose Connect and sign in.

https://listshack.com/api/mcp

What happens when you connect

  1. Add the URL above to your client and start the connection.
  2. Sign in to ListShack or create an account in the browser window that opens.
  3. Choose the ListShack account the agent will use. Each client is bound to one account at a time.
  4. Choose what the agent may do: view databases (catalog.read), search and count (search.read), buy lists with your credits (lists.purchase), preview masked records (records.preview), geocode addresses (geo.read), view suppression lists (suppressions.read), manage suppression lists (suppressions.write), append data to your own records with your credits (records.append).
  5. Approve, return to your client and ask the agent to check your ListShack access.
  6. Review or revoke the connection any time in Connected apps.

What you can ask

The user guide lists the questions your assistant can answer with ListShack, what each costs and the limits. Connected assistants also receive it from the MCP server, with starter prompts.

What you can ask ListShack in your AI assistant

Your account and allowance, the databases and their fields, record counts, saved searches, masked previews and list purchases.

Tools: get_access_statuslist_databasesdescribe_databasesearch_field_valuescount_recordscreate_searchpreview_recordspurchase_listget_purchase_status

Addresses, places and radius searches

Look up and validate US addresses, find cities, counties and ZIP codes, count records within a radius and buy records within a radius.

Tools: geocode_addressreverse_geocodevalidate_addresseslookup_geography

Suppression lists

See, create and add to your phone, email and address suppression lists, check entries, leave suppressed people out of counts, leave them out of purchases and remove entries or archive lists with your approval.

Tools: list_suppression_listscreate_suppression_listadd_to_suppression_listremove_from_suppression_listarchive_suppression_listcheck_suppressionget_suppression_job_status

Filling in your own records (appends)

Match your own contacts to ListShack records and add missing phones, emails, names or addresses, after you approve the exact cost.

Tools: quote_appendappend_recordsget_append_results

If an agent on a free plan asks for a paid tool, it gives you a link to choose a plan. Agents never pay or upgrade for you.

Free calls and credits

  • Free plans include 500 data calls a month, shared by every connected app and reset at 00:00 UTC on the 1st. Paid plans have unlimited data calls.
  • Geocoding has its own monthly allowance and never uses data calls: 25,000 lookups on free plans and 250,000 on paid plans.
  • Purchases spend your ListShack credits, exactly as a purchase in the app does, and only after you confirm; approval links expire after 15 minutes. Retrying the same purchase never charges twice.
  • Appends spend credits only after you approve the exact cost.
  • If your plan includes search suppressions, searches and counts leave out records your account already bought, so a new list doesn't repeat old leads. The agent can include them on request.

Privacy

  • Counts and field values are aggregates. Values and counts below 25 records are hidden, and larger counts are rounded to the nearest 10.
  • No free tool returns names, addresses, phone numbers, emails or other contact details.
  • Previews mask names, addresses, phone numbers and identifiers.
  • Purchased lists are delivered to your ListShack account, where you download them as usual.
  • OAuth scopes only identify you; the agent gets only the permissions you approve, checked on every request.

Direct REST API

Every MCP tool has a REST operation that uses the same OAuth access token, account, permissions and free allowance. Send the token as Authorization: Bearer <access-token>, and send a UUID in X-ListShack-Request-Id on metered and purchase requests so retries are safe.

API reference · Try it with OAuth · OpenAPI specification · Plans and pricing · Privacy · Terms

Try it with OAuth signs you in with PKCE and keeps the token only for that browser session. Headless and unattended clients are not supported.

REST examples

Get an access token through Try it with OAuth or your own OAuth client with PKCE, and use it as ACCESS_TOKEN. For each metered request, set REQUEST_ID to a new UUID. Reuse the same UUID and request body only to retry that request, including after a timeout.

Check the approved account and allowance

Requires a current OAuth connection; no additional data capability. Does not consume the free allowance.

curl --fail-with-body --include 'https://listshack.com/api/v1/access-status' \
  --header "Authorization: Bearer ${ACCESS_TOKEN}"

Discover logical database IDs and supported criteria

Required capabilities: catalog.read. Does not consume the free allowance.

curl --fail-with-body --include 'https://listshack.com/api/v1/databases' \
  --header "Authorization: Bearer ${ACCESS_TOKEN}"

Count a cohort without returning lead records

Required capabilities: search.read. Consumes one free account call on success.

curl --fail-with-body --include 'https://listshack.com/api/v1/count-records' \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --header "X-ListShack-Request-Id: ${REQUEST_ID}" \
  --json '{"database_id":"consumeremteladdr262","use_case":"direct_mail","filter":{"field":"state","operator":"eq","value":"CO"}}'

Metered responses report usage in X-ListShack-Free-Usage. A hidden count is not zero. On 429, wait for the returned reset time; on 401, reconnect; on 403, review the connection's permissions; after 409, check the conflict before using a new request ID.

Questions? Read the MCP support guide or contact ListShack support.