Optional agent integrations

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

Setting up an AI session for the first time? Use Set up your AI agent. 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:

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

Connector tools#

ToolWhat it does
run_playbookCreate an asynchronous Playbooks generation job for a target company, selling as the connected project's default brand when it has one.
run_prospectingCreate 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_cycleStart one Audience cycle for an existing saved campaign in the connected project.
run_infinite_intentRun an 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_contactsFill contact and company fields from the platform's data: up to 10 contacts synchronously, up to 1,000 as an asynchronous batch.
get_job_statusPoll an asynchronous job's status, progress, and stage timeline.
share_playbookGet the password-protected public share link for a succeeded Playbooks job's branded, rendered page. Repeated calls return the same link.
get_job_resultsFetch 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_summaryMonth-to-date usage, quotas, usage tier, and prepaid-credit balance for the connected project.
get_pricing_estimatesTypical price of one unit of each capability at the connected organization's rates, for quoting before running work.
list_chargesWhat 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, 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, Managing your clients with projects, and Billing and auto-recharge.

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#

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:

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

Cursor#

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

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

VS Code agent mode#

Create .vscode/mcp.json in the workspace:

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

Client configuration formats follow the current official setup references for Claude Code, Codex, Cursor, and VS Code.

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.

---
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#

ResourceURLUse
Documentation indexllms.txtCurated guide descriptions and direct Markdown links.
OpenAPIDownload JSONExact paths, authentication, fields, enums, constraints, and response schemas.
Documentation MCPhttps://engine.neraperla.com/docs/mcp/Search and retrieve canonical public pages with citation URLs.
Platform MCP connectorhttps://engine.neraperla.com/mcpOAuth-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.