---
title: "WhoLayer for AI agents: MCP servers, llms.txt, OpenAPI, and spend controls"
description: "What AI agents can do with WhoLayer today: an authenticated data MCP server, a public docs MCP server, llms.txt and markdown pages, an OpenAPI spec, a machine-readable compliance policy, and spend caps."
url: https://wholayer.com/for-agents
---

For agents

# WhoLayer for AI agents

Everything an agent can use today: two MCP servers, a REST API with an OpenAPI spec, markdown for every page, and limits that keep an agent's spending where you set it.

## What WhoLayer is

WhoLayer identifies website visitors and enriches them with verified emails and mobiles, then sends them to Slack, HubSpot, Klaviyo, signed webhooks, or an AI agent. One tag powers Visitor ID (people and companies visiting a B2B site; person-level for US traffic only, company-level free and unlimited) and Shopper ID (anonymous US shoppers sent to Klaviyo). The Data API and MCP server give code and AI agents the same identity and contact data with per-key spend caps, and Identity Cloud licenses identity data to platforms. Every product draws from one credit wallet. Opted-out people are never returned or charged.

## Surfaces at a glance

| Surface | URL | Auth |
| --- | --- | --- |
| Data MCP server (13 tools) | `https://mcp.wholayer.com/mcp` | OAuth sign-in or API key (Bearer) |
| Docs MCP server (5 tools) | `https://mcp.wholayer.com/docs` | None |
| REST API | `https://api.wholayer.com/v1` | API key (Bearer) |
| OpenAPI 3.1 spec | [/openapi.json](https://wholayer.com/openapi.json) | None |
| Site index for LLMs | [/llms.txt](https://wholayer.com/llms.txt) and [/llms-full.txt](https://wholayer.com/llms-full.txt) | None |
| Markdown version of any public page | Add `.md` to the URL (home is [/index.md](https://wholayer.com/index.md)), or send `Accept: text/markdown` | None |

## Data MCP server

The same identity and contact data as the REST API. Clients that support MCP sign-in (OAuth 2.1 with PKCE), such as claude.ai, ChatGPT, and Claude Code, connect with just the URL: the person approving picks the workspace, read-only or read-write access, and a daily credit cap (100 by default). Everything else uses an API key from **Settings, API keys**. A `wl_test_...` key returns sandbox data from every tool and never spends credits, so start there.

```
claude mcp add --transport http wholayer https://mcp.wholayer.com/mcp \
  --header "Authorization: Bearer wl_test_YOUR_KEY"
```

Steps for claude.ai and ChatGPT connectors, plus install snippets for Claude Desktop, Cursor (one click), VS Code, and other clients, are on the [MCP docs](https://wholayer.com/docs/mcp).

| Tool | What it does | Credits | Read-only key |
| --- | --- | --- | --- |
| `enrich_person` | Find a person's verified work email, personal email, and/or mobile from a LinkedIn URL, an email, or name + company domain. | 1 credit per work email, 2 per personal email, and 5 per mobile returned, plus 10 for a reverse lookup when you send only an email and we find the person. Nothing if no match. | No |
| `search_people` | Find people by title, seniority, department, company size, industry, and country. Returns profiles without contact details (use enrich\_person to reveal). | 1 credit per 10 results returned, rounded up; nothing if none. | No |
| `verify_emails` | Check deliverability for up to 1,000 email addresses, graded A (safe) to F (will bounce). | 0.25 credits per address. | No |
| `lookup_phone` | Find a mobile number with a live carrier and line-type check, by person\_id, email, LinkedIn URL, or name + company domain. | 5 credits when a mobile is returned; nothing if not found. | No |
| `get_company` | Company profile from a domain: size, revenue range, industry, HQ. | 1 credit when a profile is returned; nothing if not found. | Allowed |
| `list_visitors` | People and companies identified on your sites, newest first. | Free. | Allowed |
| `get_balance` | Credits remaining, plan, monthly spend cap, and this key's daily cap. | Free. | Allowed |
| `estimate_cost` | Quote the most credits an operation could spend before running it: enrich (with reveal), phones, verify (with rows), company, search (with limit), or bulk (with rows and reveal). We only charge on hits, so the real cost is the same or lower. | Free. | Allowed |
| `get_compliance_policy` | Machine-readable rules WhoLayer enforces: US-only person-level identification, consent outside the US, Global Privacy Control, blocked sensitive-page categories, suppression sources and reason codes, and retention periods. | Free. | Allowed |
| `report_bad_data` | Report a wrong person, a bounced email, or outdated data, by result\_id (the per\_… id from enrich\_person) or identity\_id (a visitor's person\_id from list\_visitors). Credits charged for a reported result are refunded if it was charged in the last 30 days, once per result. Refunds in any rolling 30 days are capped at 10% of the credits the workspace spent in that window; reports above the cap wait for review by our team and nothing is refunded automatically. The result is not delivered again. | Free. | No |
| `create_job` | Queue an enrich or verify job of up to 100,000 rows that runs in the background. Returns a job id right away; poll it with get\_job. Each row is billed like a single call, and the whole job never spends more than max\_credits (default 250). Optional webhook\_url gets a signed job.completed or job.failed event. Results are kept 30 days. | 1 credit per work email, 2 per personal email, and 5 per mobile returned, plus 10 for a reverse lookup when you send only an email and we find the person. Nothing if no match. Verify rows: 0.25 per address. | No |
| `get_job` | Status, progress, and credits used for a job from create\_job, plus a page of results (up to 100 rows per call; pass cursor for the next page). Withheld people come back as rows with error.code person\_not\_available and a reason. | Free. | Allowed |
| `add_to_suppression` | Adds emails or SHA-256 email hashes to this workspace's suppression list. Listed people are never returned, delivered, or charged for in this workspace. Emails are hashed on arrival; only hashes are stored. Removing entries is only possible from the dashboard (Settings, Suppression list), so confirm with the user before calling. | Free. | No |

Every tool returns `credits_used` and `credits_remaining`. REST responses carry an `X-Credits-Remaining` header.

## Docs MCP server

Read-only access to WhoLayer's public website, pricing, and help center. No key, no credits, and it never sees customer data.

```
claude mcp add --transport http wholayer-docs https://mcp.wholayer.com/docs
```

| Tool | What it does |
| --- | --- |
| `search_docs` | Search every public WhoLayer page and help article. Returns paths, titles, and snippets. |
| `read_page` | Return the markdown of any public wholayer.com page, e.g. /pricing or /help/mcp-setup. |
| `get_pricing` | Plans, monthly prices, included credits, overage rates, and credit costs per action. |
| `get_products` | The four WhoLayer products with what each does, features, integrations, and pricing notes. |
| `list_help_articles` | Every help center article with its category, summary, and markdown URL. |

## Spend controls and safe retries

- **Per-key daily cap.** Give each agent its own key with a maximum number of credits per day. When it's reached, calls return `credits_exhausted` until the next day.
- **Monthly spend cap.** A workspace-wide hard limit, set on the Usage page.
- **Per-call ceiling.** One call can't spend more than 250 credits unless you raise it with the `X-Max-Credits` header (REST) or the `max_credits` argument (MCP), up to 10,000.
- **Read-only keys.** Limited to the tools marked “Allowed” above, for agents that should never reveal contact details.
- **Idempotency.** Send an `Idempotency-Key` header on REST POST requests; a retry within 30 days returns the stored result without charging again. On the MCP server, repeated identical calls to paid tools within 30 days return the cached result for free.
- **Rate limits per key.** Free 2, Starter 10, Growth 25, Scale 100, Platform 1,000 requests a second. Bulk calls take up to 1,000 rows.

## Compliance rules agents can read

The rules WhoLayer enforces are published as JSON at `GET /v1/policy` (any API key, including read-only) and through the `get_compliance_policy` MCP tool: US-only person-level identification, consent outside the US, Global Privacy Control, blocked sensitive-page categories, suppression sources, and retention periods.

When a person can't be returned, the API answers HTTP 451 with `error.code` `person_not_available` and one of these reasons. You're never charged for them:

| Reason | Meaning |
| --- | --- |
| `opted_out` | This person has opted out of WhoLayer. No data is returned and you were not charged. |
| `drop_deleted` | This person asked to be deleted through California's Delete Request and Opt-out Platform (DROP). No data is returned and you were not charged. |
| `customer_suppressed` | This person is on your workspace's suppression list. No data is returned and you were not charged. |
| `non_us` | Person-level data is available for US visitors only. No data is returned and you were not charged. |
| `sensitive` | People are never identified on sensitive pages. No data is returned and you were not charged. |

Agents can add people to your workspace's suppression list with `add_to_suppression` or `POST /v1/suppression`.

Contacting people is your responsibility. If your agent emails, calls, or texts the people it finds, follow the [Acceptable Use Policy](https://wholayer.com/legal/acceptable-use), including CAN-SPAM and TCPA consent rules for calls and texts.

## Credit costs

| Action | Credits | Note |
| --- | --- | --- |
| Company identified (who's visiting, at the account level) | Free | Unlimited on every plan |
| Person identified on your site (name, title, LinkedIn, work email) | 1 | Only charged when we return a person. Repeat visits by the same person in a month are free. |
| Shopper identified for ecommerce (new to your list: verified personal email, sent to Klaviyo or your email platform) | 2 | With a Shopper ID email platform connected, charged once per new shopper, and refunded (within the refund limit) if they bounce or mark you as spam within 30 days on platforms that report it; without one, once per shopper per month. On platforms where we can't check your list first, every match is charged at this price. Opted-out people are never returned. |
| Shopper recognized who is already on your email list (no duplicate created; triggers a Returning Shopper event) | 1 | Half the price of a new shopper, on platforms where we can check your list first. Return visits we recognize by our own cookie or your site's hashed email are free, and so are holdout shoppers. |
| Work email found and verified | 1 | No charge if we don't find one. |
| Personal email found and verified | 2 | No charge if we don't find one. |
| Reverse email lookup (send an email, get the person: name, title, company, LinkedIn) | 10 | Only when you send an email alone and we find the person. No charge if we don't. |
| Mobile number with carrier and line-type check | 5 | No charge if we don't find one. |
| Email verification only | 0.25 | 4 verifications per credit. |
| People search results (name, title, company; no contact details) | 1 per 10 | Charged per 10 results returned, rounded up. Contact details are charged separately when you enrich a result. |
| Company profile (size, revenue, industry) | 1 | No charge if we don't have one. |

Plans and overage rates are on [pricing](https://wholayer.com/pricing). Everything on this page is generated from the same constants the code charges and enforces.

## Related

- [MCP server docs and install snippets](https://wholayer.com/docs/mcp)
- [REST API reference](https://wholayer.com/docs/api)
- [Data API and MCP product page](https://wholayer.com/products/data-api)
- [Moving off Explorium](https://wholayer.com/switch/explorium)