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

# Agents

# Agents guide

This page is the agent-facing entry point to Pipecorn. If you are an AI agent or LLM tool helping a user integrate with Pipecorn, read this first — it tells you which surface to use, the conventions to follow, and the auth flow.

Looking for the full docs in a single file? See [`llms-full.txt`](https://docs.pipecorn.com/llms-full.txt). For a short navigational index, see [`llms.txt`](https://docs.pipecorn.com/llms.txt).

## What Pipecorn is

Pipecorn is a B2B sales intelligence platform. Three primary jobs:

1. **Find companies** matching a profile (firmographics, technographics, buying signals).
2. **Find people** at those companies (titles, seniority, locations, industries).
3. **Enrich contacts** with verified business email and phone via waterfall sourcing across 20+ providers.

## Pick your integration surface

| Surface                   | When to use                                                                                                                     | Docs                                                                                                   |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| **MCP server**            | You are an LLM tool (Claude, ChatGPT, Cursor, Claude Code, Cline). Highest leverage — 31 tools, OAuth or API-key, no glue code. | [MCP docs](https://docs.pipecorn.com/mcp/overview)                                                     |
| **REST API**              | You are integrating Pipecorn into custom backend code or workflow tools (Zapier, Make, n8n via HTTP).                           | [API reference](https://docs.pipecorn.com/api-reference/main-use-cases)                                |
| **CLI (`@pipecorn/cli`)** | You are scripting against Pipecorn from a shell, CI, or local automation. JSON output, structured exit codes.                   | [CLI docs](https://docs.pipecorn.com/cli/overview), [source](https://github.com/pipecorn/cli-pipecorn) |

When in doubt: use MCP. It already exposes the most common workflows and handles auth, polling, and credit warnings for you.

## MCP quick reference

* **Endpoint:** `https://mcp.pipecorn.com/mcp`
* **Transport:** Streamable HTTP
* **Auth:** OAuth (Claude, ChatGPT) or `X-API-Key` header (Claude Code, Cursor, custom clients)
* **Tool count:** 31, across accounts, leads, contacts, lists, personas, signals, jobs, and utilities
* **Discovery:** [`/.well-known/mcp.json`](https://docs.pipecorn.com/.well-known/mcp.json)
* **OAuth metadata:** `https://mcp.pipecorn.com/.well-known/oauth-authorization-server`

## Conventions agents must follow

These aren't optional — they're how you avoid burning the user's credits and surfacing wrong results.

1. **Preview before extracting.** For lead and account search, call the `preview_*` variant first to estimate result count and credit cost. Only run the extracting variant after the user confirms.
2. **Resolve industries by name.** Before any search with an industry filter, call `search_industries` to get the LinkedIn industry ID. Do not guess IDs.
3. **Resolve locations by name.** Same pattern: call `search_locations` before any geo-filtered search.
4. **Poll asynchronous jobs.** Several endpoints return a job ID. Poll `get_job_result` with exponential backoff (start at 2s, cap at 30s). Never tight-loop.
5. **Check credits for bulk work.** Call `get_credits` before bulk enrichment or large extractions. If estimated cost exceeds remaining credits, warn the user and stop. Read the response carefully: only `credits.enrichment` is the spendable balance; `credits.daily_profile_scraping` and `credits.*_company_import` are remaining plan quotas for extraction, which reset on their own and cannot be topped up. See [Credits vs limits](https://docs.pipecorn.com/api-reference/credits-vs-limits).
6. **Use `bulk_enrich_contacts` for 2+ contacts.** `single_enrich_contact` is for one-offs; bulk is cheaper and faster (max 100 per call).
7. **Branch on the credit and limit error codes.** Over REST, an exhausted balance is `402` with `code: "insufficient_credits"` and a `top_up_url` — surface that link and stop, do not retry. A workspace weekly limit is `403` with `code: "workspace_limit_exceeded"`; buying credits will not lift it, so stop and tell the user to ask a workspace admin. An exhausted extraction quota is `422` with the message `"Can't proceed with the request. Plan limit reached."`; it resets daily or monthly and credits do not help either. See [Credit and limit errors](https://docs.pipecorn.com/api-reference/errors).

## Authentication

Generate an API key at [https://app.pipecorn.com/settings/apis/keys](https://app.pipecorn.com/settings/apis/keys).

* **REST:** `X-API-KEY: <key>` header. See [auth docs](https://docs.pipecorn.com/essentials/authentification).
* **MCP via OAuth:** Handled by the client (Claude, ChatGPT). No key needed.
* **MCP via API key:** `X-API-Key: <key>` header. Used by `mcp-remote`, Claude Code, Cursor, and any client supporting custom headers.
* **CLI:** `PIPECORN_API_KEY` env var, or `~/.config/pipecorn/credentials.json` (mode 0600).

CLI exit codes for programmatic callers: `0` success, `1` API error, `2` input error, `3` auth, `4` rate limit, `5` credits or plan limit exhausted.

## OpenAPI specs

The REST API is currently documented as fragments under `api-reference/specs/` (`accounts.json`, `leads.json`, `enrichments.json`, `sync-enrichments.json`, `intents.json`, `personas.json`, `list.json`, `miscellaneous.json`). A unified spec with `operationId`s and `x-mcp-tool` cross-references is on the roadmap.

## Repository layout

* `docs.json` — Mintlify config: tabs (Get Started, API Reference, CLI, MCP), navbar, footer
* `introduction.mdx` — docs landing
* `api-reference/` — MDX pages and OpenAPI fragments under `specs/`
* `mcp/` — MCP overview, per-client setup, tool reference, example workflows
* `cli/` — CLI overview and command reference (mirrors the `cli-pipecorn` README)
* `essentials/` — authentication and concepts
* `changelog.mdx` — release notes
* `llms.txt` — machine-readable navigational index for LLMs
* `llms-full.txt` — full docs as a single file, auto-generated by Mintlify at the served URL
* `.well-known/mcp.json` — machine-readable MCP server discovery
* `.well-known/ai-plugin.json` — legacy ChatGPT plugin manifest

## Contact

Issues with the agent surface: [mathieu@prontohq.com](mailto:mathieu@prontohq.com).