Remote MCP and API support

Help with connecting an agent to ListShack and with the agent API. The MCP server is in private beta and not yet open to the public.

Connect your client to https://dev.listshack.io/api/mcp and sign in with OAuth. There are no static API keys.

OAuth sign-in and reconnect

Start the connection from your MCP client and finish signing in to ListShack in your browser. Identity scopes such as openid, profile, and email identify the signed-in user; ListShack data capabilities are reviewed separately on the consent screen. If a token expires, use the client's normal reconnect flow. Do not copy a refresh token into a config file or support request.

To change the selected ListShack account, revoke the existing connection and reconnect. Each client is bound to one account at a time. You can review or revoke clients under Connected apps.

Quota and upgrade responses

get_access_status reports the plan, the connection's permissions, remaining free calls and their reset time. Free plans include 500 data calls a month, shared by MCP and REST for the selected account; paid plans are unlimited. A quota error is a failed tool result with a reset time and a link to choose a plan; it does not mean the data request succeeded.

Counts and field values are aggregates: values and counts below 25 records are hidden and larger counts are rounded to tens. Previews and purchases need a paid plan. A purchase spends credits only after you confirm it, in the chat or on the ListShack approval page the agent links to (the link expires after 15 minutes). Purchased lists are delivered to your ListShack account.

Common API responses

  • 401: sign in again or reconnect; an invalid or expired token was rejected.
  • 403: the connection lacks a required ListShack capability or current account access.
  • 402: a paid operation needs an eligible plan or entitlement.
  • 409: an idempotency ID was reused for different request contents.
  • 429: the account allowance or a traffic limit was reached; check the returned reset information.
  • 503: the service is unavailable; retry later with the same request ID.

For delegated REST calls, send a stable UUID as X-ListShack-Request-Id and reuse it only for retries of the same request.

Direct REST documentation

API reference · Try it with OAuth · OpenAPI specification · MCP setup · Direct REST examples

Try it with OAuth gets a token through OAuth PKCE and keeps it only for the current browser session; sign out to clear it. Headless and unattended clients are not supported.