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.
- In claude.ai, open Settings → Connectors and choose Add custom connector.
- Enter
https://engine.neraperla.com/mcpas the remote MCP server URL. - 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.
- 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/mcpConnector 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 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, 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:
- In claude.ai, open Settings → Connectors and choose Add custom connector.
- 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. - 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#
| Resource | URL | Use |
|---|---|---|
| Documentation index | llms.txt | Curated guide descriptions and direct Markdown links. |
| OpenAPI | Download 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.