> ## Documentation Index
> Fetch the complete documentation index at: https://docs.perceptlayer.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Perceptlayer is a web data API: one key for structured JSON from about 250 websites. Base URL https://api.perceptlayer.com.
> Send the key in the X-API-Key header. GET parameters go in the query string; POST parameters in a JSON body.
> A successful call costs the credits on its endpoint (X-Credits-Used); failed calls cost nothing. Errors are {"error": {"code", "message", "request_id"}}.
> AI agents can use every endpoint through the MCP server at https://api.perceptlayer.com/mcp (tools search_endpoints, get_endpoint, call_endpoint), with Authorization: Bearer <key>.
> Get a free key at https://perceptlayer.com/signup.

# AI agents (MCP)

> Give an AI agent the whole catalogue through our MCP server.

Agents can use every endpoint through our MCP server, over Streamable HTTP:

```
https://api.perceptlayer.com/mcp
```

It has three tools, so the agent searches the catalogue instead of loading every endpoint into its context:

| Tool | What it does | Cost |
| - | - | - |
| `search_endpoints` | Finds endpoints for a site or kind of data, such as "airbnb listing". | Free |
| `get_endpoint` | Lists one endpoint's parameters, with an example and its credit cost. | Free |
| `call_endpoint` | Runs an endpoint and returns its JSON. | The endpoint's credits |

`call_endpoint` needs your key. Send it as `Authorization: Bearer sk_live_...`.

## Connect a client

**Claude Code**

```bash theme={"dark"}
claude mcp add --transport http perceptlayer https://api.perceptlayer.com/mcp \
  --header "Authorization: Bearer $API_KEY"
```

**Cursor**

Add to `~/.cursor/mcp.json`, or `.cursor/mcp.json` in a project:

```json theme={"dark"}
{
  "mcpServers": {
    "perceptlayer": {
      "url": "https://api.perceptlayer.com/mcp",
      "headers": { "Authorization": "Bearer sk_live_..." }
    }
  }
}
```

**VS Code**

Add to `.vscode/mcp.json`. VS Code asks for the key once and stores it:

```json theme={"dark"}
{
  "inputs": [
    { "type": "promptString", "id": "perceptlayer-key", "description": "Perceptlayer API key", "password": true }
  ],
  "servers": {
    "perceptlayer": {
      "type": "http",
      "url": "https://api.perceptlayer.com/mcp",
      "headers": { "Authorization": "Bearer ${input:perceptlayer-key}" }
    }
  }
}
```

Other clients that support remote MCP servers need the same URL and header.

## Limits

* Calls through MCP follow the same rules as the API: failed calls are free, [rate limits](https://docs.perceptlayer.com/rate-limits.md) apply, and [restricted endpoints](https://docs.perceptlayer.com/restricted-endpoints.md) need the terms.
* Responses longer than 100,000 characters are cut short. Use an endpoint's paging or limit parameters for large results.
* Connect from a desktop app, a command-line tool or your own server. MCP clients that run in a web browser aren't supported yet.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.