# Clay setup for PopMCP

You paste one Clay API key. It belongs to your Clay user and works in the workspace you create it in.

- Auth: API credentials
- Setup time: 3 min
- API base URL: https://api.clay.com/public/v0
- Credentials screen: https://app.clay.com/workspaces/~/api-and-cli?tab=api-keys
- Provider docs: https://developers.clay.com/public-api/authentication

## Before you begin

- A Clay account and the workspace you want the AI to work in
- API access turned on for each Clay function the AI should run (Functions, Details, API). Without it a run answers 404.
- Clay credits for function and workflow runs. Searches spend no credits but count toward your plan's result limits.
- A Clay Enterprise plan, only if you want the AI to query Clay tables

## Get your credentials

### 1. Open API keys in Clay

Sign in to Clay, switch to the workspace you want to connect, and open API and CLI, then the API keys tab. If your workspace does not show API and CLI, look under Settings, Account, API keys.

Screen: https://app.clay.com/workspaces/~/api-and-cli?tab=api-keys

### 2. Create a key and copy it

Create a new API key, name it `PopMCP` so you can recognize it later, and copy it straight away: Clay returns the full key only once.

Screen: https://app.clay.com/workspaces/~/api-and-cli?tab=api-keys

### 3. Turn on API access for the functions the AI will run

Open Functions, select a function, open Details and enable API. Copy the function's `t_...` id (or its URL) so you can hand it to the AI, because the Public API cannot list functions. Turning on MCP or Claygent access does not turn on API access.

Screen: https://app.clay.com/functions

### 4. Paste the key into PopMCP

In PopMCP, paste the key into API key and connect. There is no OAuth app or redirect URL to set up.

## Fields PopMCP asks for

- API key (apiKey) [required]: In Clay, open API and CLI, then the API keys tab. Create a key and copy it (Clay shows it only once). It works for the workspace you created it in. Stored encrypted and used only on our servers.

## Verify

PopMCP shows Clay as Connected with your workspace name and email, and clay_get_credit_balance returns the workspace's credit balances without spending any.

## Troubleshooting

### "Clay rejected this API key"

Cause: Clay answered 401 or 403 (body: "Authentication failed"): the key was revoked, mistyped or cut off.

Fix: Create a new key under **API and CLI**, **API keys**, copy it while it is on screen, and paste it into **API key**.

### Running a function returns 404

Cause: API access is off for that function, the id is wrong, or the function lives in a different workspace from the key.

Fix: Open the function under **Functions**, **Details**, enable **API**, and give the AI its `t_...` id or URL from the same workspace as the key.

### A search returns HTTP 402

Cause: The search hit your plan's result limit. Free and Trial plans cap a search at 50 results.

Fix: Narrow the search or ask for fewer rows, or move to a plan with higher limits.

### Table queries fail

Cause: Tables are an Enterprise feature, and there is no endpoint that lists tables.

Fix: On Enterprise, give the AI the table's `t_...` id from its URL (app.clay.com/workspaces/<workspace>/tables/t_...).

### A run stays in_progress or answers 202

Cause: Runs are asynchronous, and 202 means the run has not finished.

Fix: Poll again after a few seconds, or use clay_run_routine_and_wait for up to 100 rows, which waits and returns every row's result.

### 429 Too Many Requests

Cause: The workspace went over Clay's per-workspace request rate.

Fix: Wait for the Retry-After interval Clay sends and retry. PopMCP retries rate-limited calls automatically.

---

Source: https://www.docs.popmcp.com/docs/integrations/clay/