# Connect Ecommerce Leads to your AI app (MCP + OAuth)

Instructions for an AI assistant. Read all of this page. Then guide the user step by step.

## Server details

- Name: Ecommerce Leads
- URL: https://getecommerceleads.com/api/mcp
- Transport: Streamable HTTP (remote MCP server)
- Authentication: OAuth 2.1 with PKCE. The user logs in with an email and a 6-digit code.
- Client ID and client secret: not needed. The server registers the app by itself (dynamic client registration).
- Do not use an API key for this flow.
- The user needs an Ecommerce Leads account.

## Step 1: Find the user's app

Ask which app the user has: Claude, ChatGPT, Claude Code, Cursor, or other.

## Step 2: Add the server

Claude (claude.ai or desktop):
1. Open Settings, then Connectors.
2. Select "Add custom connector".
3. Enter the URL https://getecommerceleads.com/api/mcp and save.
4. Select "Connect".

ChatGPT:
1. Open Settings, then Connectors, then Advanced. Turn on Developer mode.
2. Add a connector with the URL https://getecommerceleads.com/api/mcp.
3. Choose OAuth as the authentication method.

Claude Code:
1. Run this command:
   claude mcp add --transport http ecommerce-leads https://getecommerceleads.com/api/mcp
2. Start Claude Code. Run /mcp. Select ecommerce-leads. Select "Authenticate".

Cursor and other apps:
1. Add this entry to the MCP settings file (mcp.json in Cursor):
   { "mcpServers": { "ecommerce-leads": { "url": "https://getecommerceleads.com/api/mcp" } } }
2. Use the app's "Connect" or "Authenticate" button for the server.

Menu names can change between app versions. If a menu name is different, look for "connectors" or "MCP servers".

## Step 3: Log in

1. A browser window opens on getecommerceleads.com.
2. The user enters the account email.
3. The user gets a 6-digit code by email. The user enters the code.
4. The consent screen shows the app name and the redirect host. The user checks that the host matches the app.
5. The user selects "Allow". The browser returns to the AI app.

## Step 4: Test

Call the tool searchStores with no filters. Tell the user if it returns stores.
Without a login, only the lookupStore tool works. It returns store data and buying signals. It does not return decision makers.

## Rules for the assistant

- revealStores spends credits. Always call getRevealCost first. Ask the user to confirm before you call revealStores.
- addToWatchlist spends 1 credit per new domain. Ask the user to confirm first.
- Ask the user to confirm before you call deleteWatchlist, deleteSignalSet or saveSignalSet with a setId (it overwrites).
- Typical flow: searchStores, then getRevealCost, then the user confirms, then revealStores, then getRevealStatus until done, then lookupStore to read the contacts.
- Search results have 30 rows per page. Call searchStores again with page + 1 while hasMore is true.
- Rate limit: 60 requests per minute.

## Tools

searchStores, lookupStore, getStoreChart, listSignalSets, getSignalSet, previewSignalSet,
listWatchlists, getWatchlist, getRevealCost, getRevealStatus, revealStores, saveSignalSet,
deleteSignalSet, createWatchlist, renameWatchlist, deleteWatchlist, removeFromWatchlist, addToWatchlist,
updateOutreachStatus, sendFeedback, exportStores.
Full list with descriptions: https://getecommerceleads.com/docs

## Tokens and disconnect

- Access tokens last 1 hour. Refresh tokens last 30 days. The app refreshes them by itself.
- The user can disconnect at any time: Settings > Integrations on getecommerceleads.com, then "Revoke".
- After a revoke, the next MCP call returns 401. The user must connect again.

## If a step fails

Tell the user the exact error. Suggest one fix. Do not guess.
- 401 after login: the user must connect again.
- 402 from revealStores: the credit balance is too low. Show the cost and balance.
- 429: wait one minute.
- Support: https://getecommerceleads.com/docs