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://dev.listshack.io/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 mcp add --transport http listshack https://dev.listshack.io/api/mcp

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

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

https://dev.listshack.io/api/mcp

https://dev.listshack.io/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), preview masked records (records.preview) and buy lists with your credits (lists.purchase).
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.

Tools

Free on every plan

• get_access_status: your plan, the agent's permissions, remaining free calls and credits.
• list_databases and describe_database: the databases you can search and their fields.
• search_field_values: look up allowed values for a field, such as states or vehicle makes.
• count_records: how many records match a set of filters.
• create_search: save a search the agent can preview or buy from; it returns the count.

With a paid plan

• preview_records: up to three masked sample records from a search. Spends no credits.
• purchase_list: buy a list from a search. The agent shows you the record count, fields, list name and exact credit cost, and nothing is spent until you confirm. If your client can't ask you in the chat, the agent gives you a link to approve the purchase on ListShack; links expire after 15 minutes.
• get_purchase_status: check a purchase and get the link to the finished list in ListShack.

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. Successful count_records, search_field_values and create_search calls count; the other tools are free.
• Paid plans have unlimited data calls.
• Purchases spend your ListShack credits, exactly as a purchase in the app does. Retrying the same purchase never charges twice.

Privacy

• Counts and field values are aggregates. Values and counts below 25 records are hidden, and larger counts are rounded to tens.
• 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.

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

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

curl --fail-with-body --include 'https://dev.listshack.io/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.