# AI and machine-readable documentation

> Fetch raw guides, documentation bundles, OpenAPI, or the read-only documentation MCP server without scraping the web application.

Canonical guide: <https://api.blackpearl.com/docs/agent-resources>

Raw Markdown: <https://api.blackpearl.com/docs/raw/agent-resources.md>

OpenAPI: <https://api.blackpearl.com/v1/openapi.json>

All resources on this page are public and read-only. They contain developer documentation and the public API contract, never project API keys or private repository content.

## Direct sources

| Resource | URL | Use |
|---|---|---|
| Playbooks agent primer | [Raw Markdown](https://api.blackpearl.com/docs/raw/playbooks-api-primer.md) | Small, complete context for the golden Playbooks flow. |
| Documentation index | [`llms.txt`](https://api.blackpearl.com/llms.txt) | Curated guide descriptions and direct Markdown links. |
| Full documentation | [`llms-full.txt`](https://api.blackpearl.com/llms-full.txt) | Deterministic bundle of every public canonical guide. |
| OpenAPI | [Download JSON](https://api.blackpearl.com/v1/openapi.json) | Exact paths, authentication, fields, enums, constraints, and response schemas. |
| Documentation manifest | [Download JSON](https://api.blackpearl.com/docs/manifest.json) | Ordered public page metadata and stable source URLs. |
| Documentation MCP | `https://api.blackpearl.com/docs/mcp/` | Search and retrieve canonical public pages with citation URLs. |

Every guide is also plain Markdown: append `.md` to its canonical URL (for example `https://api.blackpearl.com/docs/getting-started.md`), or use the equivalent `https://api.blackpearl.com/docs/raw/{slug}.md` path. Raw files and bundles are generated from canonical Markdown; they are not separately maintained prose.

## 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://api.blackpearl.com/docs/mcp/"
```

The Codex app, CLI, and IDE extension share this configuration. Restart or begin a new session, then ask Codex to search `blackpearl_docs` before implementing a Blackpearl integration.

## Claude Code

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

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

## Claude.ai and Claude Cowork

The documentation MCP server also works as a claude.ai custom connector, which makes it available in chats, projects, and Cowork sessions:

1. In claude.ai, open **Settings → Connectors** and choose **Add custom connector**.
2. Enter `https://api.blackpearl.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 or Cowork session, enable the connector from the tools menu, then ask Claude to search the Blackpearl documentation before writing integration code.

Cowork sessions that run Claude Code can instead use the `claude mcp add` command above; both paths expose the same `search_documentation` and `get_documentation` tools.

## Cursor

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

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

Enable the server under Cursor's tools settings. Cursor Agent can then search and retrieve the same Markdown published at the raw URLs.

## VS Code agent mode

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

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

Start the server from the editor, open GitHub Copilot Chat in agent mode, and enable the Blackpearl documentation tools. No credentials or request headers are required because this server exposes only public documentation.

## Suggested agent instruction

```text
Before changing a Blackpearl integration, search the blackpearl_docs MCP server.
Use get_documentation for the canonical guide and consult the published OpenAPI
for exact request and response schemas. Cite the source_url returned by the tool.
Do not infer undocumented retry, retention, idempotency, or sandbox behavior.
```

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