# Optional agent integrations

> Configure an OAuth connector, documentation tools, or a saved skill when you specifically need one.

Canonical guide: <https://engine.neraperla.com/docs/agent-integrations>

Raw Markdown: <https://engine.neraperla.com/docs/raw/agent-integrations.md>

OpenAPI: <https://engine.neraperla.com/v1/openapi.json>

Setting up an AI session for the first time? Use [Set up your AI agent](https://engine.neraperla.com/docs/agent-resources).
The integrations below are optional and separate from that connection flow.
Use them when the user explicitly chooses an integration or the session cannot
run the API-key setup procedure; do not make them extra onboarding steps.

## Use the platform from claude.ai — the platform MCP connector

The platform itself is available as a remote MCP connector: an OAuth-protected
server at `https://engine.neraperla.com/mcp` that lets Claude run real platform work in
your organization — no code and no API-key handling.

1. In claude.ai, open **Settings → Connectors** and choose **Add custom
   connector**.
2. Enter `https://engine.neraperla.com/mcp` as the remote MCP server URL.
3. Sign in to your Blackpearl account when prompted and approve the consent
   screen. Approving needs the owner or administrator role, and billing must
   be set up. Consent binds the connection to exactly one organization and one
   active project; every later tool call runs in that project. To work in a
   different project, connect again and choose it on the consent screen.
4. In a chat, project, or Cowork session, enable **Blackpearl Platform** from
   the tools menu.

Any MCP client that supports OAuth 2.1 authorization with dynamic client
registration can connect the same way. In Claude Code:

```bash
claude mcp add --transport http blackpearl-platform https://engine.neraperla.com/mcp
```

### Connector tools

| Tool | What it does |
|---|---|
| `run_playbook` | Create an asynchronous Playbooks generation job for a target company, selling as the connected project's default brand when it has one. |
| `run_prospecting` | Create an asynchronous prospecting run that discovers and qualifies prospects from a campaign name, product description, and objective, with an optional targeting `query` and `booking_url`. The run returns every prospect the agent delivers, up to 5,000. |
| `run_campaign_cycle` | Start one Audience cycle for an existing saved campaign in the connected project. |
| `run_infinite_intent` | Run an [Infinite Intent](https://engine.neraperla.com/docs/infinite-intent) programme enabled for the connected project (`world-of-claudecraft` or `coastal-retreat`), optionally naming an uploaded intent file and its row count. The result links to a hosted report that only its designated viewer can open after signing in. |
| `enrich_contacts` | Fill contact and company fields from the platform's data: up to 10 contacts synchronously, up to 1,000 as an asynchronous batch. |
| `get_job_status` | Poll an asynchronous job's status, progress, and stage timeline. |
| `share_playbook` | Get the password-protected public share link for a succeeded Playbooks job's branded, rendered page. Repeated calls return the same link. |
| `get_job_results` | Fetch a completed job's typed result; Audience results return cursor-paged candidates, and Prospecting results return their prospects 50 at a time (`prospects_page.next_cursor`). |
| `get_usage_summary` | Month-to-date usage, quotas, usage tier, and prepaid-credit balance for the connected project. |
| `get_pricing_estimates` | Typical price of one unit of each capability at the connected organization's rates, for quoting before running work. |
| `list_charges` | What each of the connected project's runs was charged, newest first, with the organization's balance after each charge. |

Creation tools return a job ID; Claude then polls `get_job_status` and fetches
`get_job_results` — the same create → poll → result flow as the
[Jobs API](https://engine.neraperla.com/docs/jobs), with the same durations, so expect a Playbooks run to
take minutes, not seconds.

Tools see only the connected project's jobs and campaigns. Prices from
`get_pricing_estimates` are organization-wide, like `GET /v1/pricing-estimates`.

### Billing, gates, and tokens

Connector runs are real runs. Every tool call passes the same admission gates
as the `/v1` API — capability entitlement, quota, budgets, the connected
project's allowance and daily and monthly limits, usage-tier cap, and prepaid
credits — and completed work is charged to your company balance and counted
against the connected project exactly like an API-key call in that project.
A refused call returns a tool error that starts with the same `error.code` as
`/v1`, for example `insufficient_credits` or `budget_exceeded`. Each connection
has its own request-rate limit, sized by your usage tier like an API key's.
If the connected project is archived, tool calls fail until it is restored. See
[Limits, budgets, and usage](https://engine.neraperla.com/docs/usage-quotas),
[Managing your clients with projects](https://engine.neraperla.com/docs/projects), and
[Billing and auto-recharge](https://engine.neraperla.com/docs/billing).

Connector access tokens are audience-bound: a connector token is rejected by
`/v1/*`, and a `bp_live_` API key, project or company-level, is rejected by
`/mcp`. Neither credential substitutes for the other.

### Manage and revoke connections

Connections are listed in the console under **Settings → Connected apps**,
where owners and administrators can revoke them. A connection never outlives the approving user's access:
removing the approver from the organization (or deactivating them) revokes the
connection, and reducing the approver's role below API-key-issuance rights
blocks it until the role is restored.

## Connect the docs to your AI

### Claude (claude.ai and Cowork)

The documentation is available as a claude.ai connector — two minutes, no
code, no credentials:

1. In claude.ai, open **Settings → Connectors** and choose **Add custom
   connector**.
2. Enter `https://engine.neraperla.com/docs/mcp/` as the remote MCP server URL. The server is public
   and read-only, so no OAuth or API key is required.
3. In a chat, project, or Cowork session, enable the connector from the tools
   menu. Claude can then search and read every guide on this site.

### Claude Code

```bash
claude mcp add --transport http blackpearl-docs https://engine.neraperla.com/docs/mcp/
```

Run `/mcp` in Claude Code to confirm the server and its `search_documentation`,
`get_documentation`, and `documentation_sources` tools are available.

### Codex

Add the Streamable HTTP server to `~/.codex/config.toml`, or use
`.codex/config.toml` in a trusted project:

```toml
[mcp_servers.blackpearl_docs]
url = "https://engine.neraperla.com/docs/mcp/"
```

### Cursor

Create `.cursor/mcp.json` for a project or `~/.cursor/mcp.json` globally:

```json
{
  "mcpServers": {
    "blackpearl-docs": {
      "type": "http",
      "url": "https://engine.neraperla.com/docs/mcp/"
    }
  }
}
```

### VS Code agent mode

Create `.vscode/mcp.json` in the workspace:

```json
{
  "servers": {
    "blackpearl-docs": {
      "type": "http",
      "url": "https://engine.neraperla.com/docs/mcp/"
    }
  }
}
```

Client configuration formats follow the current official setup references for
[Claude Code](https://docs.anthropic.com/en/docs/claude-code/mcp),
[Codex](https://learn.chatgpt.com/docs/extend/mcp),
[Cursor](https://docs.cursor.com/context/model-context-protocol), and
[VS Code](https://code.visualstudio.com/docs/agent-customization/mcp-servers).

## Optional: install the platform skill

The skill below points agents to the relevant capability guides.

Install this only when the user asks to retain the workflow for future
sessions, using the host application's normal installation/review controls.
It is not needed to connect or start work. In Claude Code, save it as
`.claude/skills/blackpearl-platform/SKILL.md`; on claude.ai, it can be added to
project instructions. Installation does not itself persist API credentials.

```markdown
---
name: blackpearl-platform
description: Drive the Blackpearl GTM data & intelligence API — create brand and offer context, run prospecting, generate playbooks and documents, record outcomes. Use when the user asks for prospecting lists, sales research, playbooks, audiences, campaigns, or GTM data and integrations.
version: 2026-10-11.1
---

# Blackpearl Platform

Blackpearl is the GTM data & intelligence API: evidence-backed prospecting,
audiences, account research, stage-aware playbooks, sales documents, message
templates, and an outcomes feedback loop, behind one API key.
Authenticate every call with `Authorization: Bearer $BLACKPEARL_API_KEY`
against `$BLACKPEARL_API_BASE_URL` (default `https://engine.neraperla.com`). With a
company-level key, also send `Blackpearl-Project` (the project's id or slug)
on requests that create work or read project data.

## Current guidance

Fetch the current task's documentation from https://engine.neraperla.com/docs/raw/ as needed.
The optional skill's canonical copy lives at
https://engine.neraperla.com/docs/raw/agent-integrations.md. Do not automatically replace this
skill or any standing instructions. Updates use the host application's normal
review/installation flow when the user requests them; they never block a
working connection.

## Rules

0. Credentials: authenticate with the key in `$BLACKPEARL_API_KEY` (or load
   `.env` explicitly). For setup or credential recovery, follow
   https://engine.neraperla.com/docs/raw/agent-setup.md. Reuse a verified key; transient network
   errors and billing/permission failures are not reasons to mint another.
   Never print a full key, a poll URL, or the raw key-delivery response.
   If using the authenticated platform MCP connector, use its tools within
   their granted scope; do not request an API key unless the user's task
   requires an API operation that connector does not expose.
1. Before planning, call `GET /v1/capabilities`. Use only capabilities with
   `enabled: true`. If the user asks for something listed with
   `enabled: false`, say it exists but is not enabled for their organization
   and must be requested — never silently work around it.
2. The only input you need from the user is their company website URL (plus
   anything they volunteer). Do not ask for industries, job titles, seniority
   levels, or company sizes — deriving targeting is the platform's job.
3. For a requested GTM task, reuse relevant Brand and Offer context. If it is
   missing, create a Brand from the company URL and run its research, then
   draft an Offer from that research. Confirm your draft in one message.
   Connection-only setup uses read-only checks and does not start paid work.
4. For prospecting, derive `product_info` and `objective` from the Brand and
   Offer. Leave the structured `target` empty unless the user explicitly
   constrains it. Don't send `limit` or `min_qualification_score`: both are
   deprecated and ignored. `qualification.score` is the search agent's
   own fit score for that run, not comparable across runs: don't cut
   prospects by score; use `qualification.status` and the evidence.
5. Read the operation's guide before executing it: some creates return
   stored objects or synchronous results; job-creating operations return an
   async job. Follow https://engine.neraperla.com/docs/raw/jobs.md for polling, timeouts, and
   recovery. Use `Idempotency-Key` where the operation supports it and reuse
   the same value on retries; never duplicate a run after a transient error.
6. Handle errors by `error.code` (machine-readable, documented per code).
   Never fabricate prospects or results; a prospect with
   `is_synthetic: true` is not an actionable lead.
7. Record real-world results through Outcomes so the system improves; the
   platform never sends outreach — delivery is your side of the integration.

## Where to look things up

Fetch only what the task needs; every page is plain Markdown:

- End-to-end workflow (start here): https://engine.neraperla.com/docs/raw/gtm-workflow.md
- Quickstart and auth: https://engine.neraperla.com/docs/raw/getting-started.md and
  https://engine.neraperla.com/docs/raw/authentication.md
- Jobs and polling: https://engine.neraperla.com/docs/raw/jobs.md
- Errors and retries: https://engine.neraperla.com/docs/raw/errors.md
- Projects, company-level keys, and charges: https://engine.neraperla.com/docs/raw/projects.md
  and https://engine.neraperla.com/docs/raw/billing.md
- Capability contracts: https://engine.neraperla.com/docs/raw/prospecting.md,
  playbooks.md, brands.md, offers.md, campaigns.md, audiences.md,
  documents.md, message-templates.md, outcomes.md (same path pattern)
- Guide index: https://engine.neraperla.com/llms.txt
- Exact request/response schemas: https://engine.neraperla.com/v1/openapi.json
- Documentation search (MCP): https://engine.neraperla.com/docs/mcp/
```

## Direct sources

| Resource | URL | Use |
|---|---|---|
| Documentation index | [`llms.txt`](https://engine.neraperla.com/llms.txt) | Curated guide descriptions and direct Markdown links. |
| OpenAPI | [Download JSON](https://engine.neraperla.com/v1/openapi.json) | Exact paths, authentication, fields, enums, constraints, and response schemas. |
| Documentation MCP | `https://engine.neraperla.com/docs/mcp/` | Search and retrieve canonical public pages with citation URLs. |
| Platform MCP connector | `https://engine.neraperla.com/mcp` | OAuth-protected; run playbooks, prospecting, campaign cycles, Infinite Intent, and enrichment, share playbooks, and read usage, prices, and charges from claude.ai or any MCP client. |

Every guide is also available at `https://engine.neraperla.com/docs/raw/{slug}.md`,
generated from the same canonical Markdown as the website.
