## Introduction

Ecommerce Leads gives you problem-based store matches with decision-maker contacts. Connect Claude, ChatGPT or any MCP client to your account over the Model Context Protocol (MCP), or use the HTTP API to run every dashboard action.

**MCP with login:** add `https://getecommerceleads.com/api/mcp` to your AI client and log in with your Ecommerce Leads account. The free `lookupStore` tool needs no login. Some account tools need a paid plan.

**API key:** log in and open the [Settings page](https://getecommerceleads.com/d/settings/integrations) to get one static API key. Use it for the HTTP API only. MCP does not accept an API key.

## Authentication

Every HTTP API request uses a static key in the `Authorization` header. MCP does not use this key (see Connect with OAuth):

```
Authorization: Bearer YOUR_API_KEY
```

To get a key, log in and open the [Settings page](https://getecommerceleads.com/d/settings/integrations).

## HTTP API

Every dashboard action also exists as a REST route under `https://getecommerceleads.com/api/`. Every call needs your API key in the `Authorization` header. There is no anonymous access. Get your key on the Settings page (see Authentication above).

The full list of routes, parameters and responses is in the OpenAPI file: [https://getecommerceleads.com/openapi.json](https://getecommerceleads.com/openapi.json).

### Route groups

- **Stores:** `/api/stores/search`, `/api/stores/lookup`, `/api/stores/chart`, `/api/stores/export` and `/api/stores/{storeId}/outreach-status`.
- **Signal sets:** `/api/signal-sets`, `/api/signal-sets/preview` and `/api/signal-sets/{setId}`.
- **Watchlists:** `/api/watchlists`, `/api/watchlists/{listId}`, `/api/watchlists/{listId}/domains` and `/api/watchlists/{listId}/domains/{domain}`.
- **Reveals:** `/api/reveals`, `/api/reveals/cost` and `/api/reveals/status`.
- **Feedback:** `/api/feedback`.

GET routes take a query string. These are `/api/stores/lookup`, `/api/stores/chart`, `/api/reveals/status` and the list and get routes for signal sets and watchlists. Every other route uses POST, PUT, PATCH or DELETE with a JSON object body. This includes `/api/stores/search`, `/api/stores/export`, `/api/signal-sets/preview` and `/api/reveals/cost`. Reveals spend credits, and so does adding a domain to a watchlist. Call `/api/reveals/cost` first to see the cost. Some routes need a paid plan.

### Example

This call is read-only. It spends no credits. It lists your watchlists.

```bash
curl https://getecommerceleads.com/api/watchlists \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Limits

Every route has this limit: each key can make 60 requests per minute. Some routes also have their own limit:

- `/api/stores/search`, `/api/stores/export`, `/api/stores/{storeId}/outreach-status`, the signal-set routes and the reveal routes share the per-user dashboard limit of 50 requests per minute with your dashboard.
- `/api/stores/lookup` allows 20 requests per minute.
- `/api/stores/chart` allows 60 requests per minute in its own bucket.
- `/api/feedback` allows 5 messages per hour.
- The watchlist routes have no limit other than the 60 requests per minute for each key.

If you go over a limit, the API returns 429. Errors have the form `{"error": "..."}`.

## MCP overview

The MCP server is at `https://getecommerceleads.com/api/mcp`. It accepts OAuth login and anonymous calls. It does not accept an API key. An API key in the `Authorization` header gets a 401 response, and your MCP client then starts the OAuth login. To run dashboard actions with an API key, use the HTTP API above.

## Connect with OAuth

Add the server URL `https://getecommerceleads.com/api/mcp`, then log in with your Ecommerce Leads email and a one-time code. Without a login, only the `lookupStore` tool works. It returns store data and buying signals. It does not return decision makers.

**Claude**

1. Open Settings, then Connectors, then Add custom connector.
2. Enter the URL `https://getecommerceleads.com/api/mcp` and save.
3. Choose Connect. Enter your email and the code we send you. Approve.

**ChatGPT**

1. Add the Ecommerce Leads plugin, or add the same URL as a custom connector in developer mode.
2. Ask for an action that needs an account. ChatGPT opens the login page.
3. Enter your email and the code we send you. Approve.

Let your AI do the setup: tell it to read [https://getecommerceleads.com/docs/connect.txt](https://getecommerceleads.com/docs/connect.txt).

Access tokens last 1 hour. Refresh tokens last 30 days. The tools use your plan, your credits and your data. Tools that spend credits are marked below. Your assistant should ask you before it uses them.

## Free tool lookupStore

`lookupStore` takes one store domain, for example `gymshark.com`. A full URL also works. It returns the store's estimated monthly revenue, marketing budget, organic and paid traffic, Google and Meta ad spend, active ad counts, a Conversion Rate Score, buying signals, the store phone number, and links to the social profiles and ad libraries. It never returns decision-maker contacts without a reveal. When other active stores share the same base domain, the reply has `sharedMetrics`: those stores show the same traffic and ad numbers.

- Without a login: 20 lookups per hour per IP address, and a daily cap shared by all users without a login.
- With a login: 20 lookups per minute. If you revealed the store, the reply also shows the contacts you revealed.
- It never spends credits.

Example prompt: *"Look up the store metrics for gymshark.com."*

## Tools for logged-in users

These 20 tools need your account. `lookupStore` is listed above. Tools marked "paid plans" need a paid plan. **Read** tools change nothing. **Write** tools change your account data. Tools that spend credits are marked. Your assistant must tell you the cost and ask you to confirm before it uses them.

| Tool | Type | What it does | Arguments |
| --- | --- | --- | --- |
| `searchStores` | Read | Search the store catalog like the dashboard. 30 rows per page. Fields of stores you have not revealed are masked. | tab, filters, sort, page, columns, includeColumns |
| `getStoreChart` | Read | The latest 24 points of one metric for a store, for a chart. | domain, metric |
| `listSignalSets` | Read | List your signal sets, with the signal catalog and the columns you can use in criteria. Paid plans. | none |
| `getSignalSet` | Read | Get one signal set with its criteria. Paid plans. | setId |
| `previewSignalSet` | Read | Check if candidate criteria match enough stores (80 or more). Saves nothing. Paid plans. | criteria, setId |
| `listWatchlists` | Read | List your watchlists and blacklist with the domain count of each. Paid plans. | none |
| `getWatchlist` | Read | The domains of one watchlist or the blacklist, 100 per page. Paid plans. | listId, page |
| `getRevealCost` | Read | Preview the credit cost of a reveal. Charges nothing and reveals nothing. | selection |
| `getRevealStatus` | Read | Status of contact searches and your credit balance. | storeIds |
| `exportStores` | Read | Export revealed stores as CSV text, up to 200 rows. Skips unrevealed stores. Paid plans. | selection, visibleColumns |
| `revealStores` | **Write — spends credits** | Reveal store details, or the CEO, marketing or ecommerce contacts. Reveals that you have already paid for cost 0. | action, selection |
| `addToWatchlist` | **Write — spends credits** | Add domains to a watchlist, 1 credit per new domain, at most 50 domains per call. | listId, domains |
| `saveSignalSet` | Write | Create a signal set, or replace the criteria of an existing set. Paid plans. | criteria, setId, name |
| `deleteSignalSet` | Write | Delete a signal set. You cannot undo this. Paid plans. | setId |
| `createWatchlist` | Write | Create an empty watchlist. You can have at most 10 lists, including the blacklist. Paid plans. | name |
| `renameWatchlist` | Write | Rename a watchlist. You cannot rename the blacklist. Paid plans. | listId, name |
| `deleteWatchlist` | Write | Delete a watchlist with all its domains. You cannot delete the blacklist. Paid plans. | listId |
| `removeFromWatchlist` | Write | Remove one domain from a watchlist or the blacklist. Paid plans. | listId, domain |
| `updateOutreachStatus` | Write | Set the outreach status of one store that you revealed. | storeId, status |
| `sendFeedback` | Write | Send a message to the Ecommerce Leads team. 5 messages per hour. | message |

## Typical flows

- *"Search my stores for Shopify apparel brands with more than 100000 monthly visits."* The assistant calls `searchStores`. For more rows, it calls the tool again with `page` + 1 while `hasMore` is true.
- *"Reveal the CEO contact for gymshark.com."* The assistant calls `getRevealCost`, states the cost, and asks you. After you agree, it calls `revealStores`, then `getRevealStatus` until the search is done, then `lookupStore` to read the contact.
- *"Create a watchlist called Q4 targets and add these domains."* The assistant calls `createWatchlist`, then `addToWatchlist` after you confirm the cost.

## Data and privacy

- The server reads and changes only the data of the account you log in with. It never returns the data of other accounts.
- Without a login, a `lookupStore` call logs the store domain and your IP address. We use this log only for rate limits and abuse prevention, and we delete it after 30 days.
- With a login, each lookup and each action that changes your account (for example a reveal or a watchlist edit) is recorded in your account data, in the same way as in the dashboard.
- You can disconnect any app: log in, open Settings, then Integrations, and select Revoke. The next call from that app returns 401.
- Privacy policy: [getecommerceleads.com/privacy-policy](https://getecommerceleads.com/privacy-policy). Support: [diogo@getecommerceleads.com](mailto:diogo@getecommerceleads.com).

## Cursor config

Cursor uses OAuth. Add this to your `mcp.json`, then log in when Cursor asks:

```json
{
  "mcpServers": {
    "ecommerce-leads": {
      "url": "https://getecommerceleads.com/api/mcp"
    }
  }
}
```

## Claude Code config

Add the server with a command, then run `/mcp` in Claude Code to log in with OAuth:

```bash
claude mcp add --transport http ecommerce-leads \
  https://getecommerceleads.com/api/mcp
```

You can also use a JSON entry with `"type": "http"`:

```json
{
  "mcpServers": {
    "ecommerce-leads": {
      "type": "http",
      "url": "https://getecommerceleads.com/api/mcp"
    }
  }
}
```
