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

# Use okraPDF with Claude

> Connect the remote okraPDF MCP server for PDF upload, citation verification, visual review, and document analysis.

## Remote MCP URL

```text theme={null}
https://api.okrapdf.com/mcp
```

okraPDF runs a remote Streamable HTTP MCP server on Cloudflare Workers. It supports OAuth discovery for clients with remote connector support, and API-key headers for clients that prefer explicit bearer tokens.

## Setup

<Tabs>
  <Tab title="Claude Desktop / Claude.ai">
    Add a custom connector with this URL:

    ```text theme={null}
    https://api.okrapdf.com/mcp
    ```

    Leave OAuth client fields blank. The server advertises discovery metadata and prompts for browser authentication on first use.
  </Tab>

  <Tab title="Claude Code">
    ```bash theme={null}
    claude mcp add -s user -t http okrapdf https://api.okrapdf.com/mcp
    ```

    If your client asks for headers instead of OAuth, use:

    ```bash theme={null}
    claude mcp add -s user -t http okrapdf https://api.okrapdf.com/mcp \
      --header "Authorization: Bearer $OKRA_API_KEY"
    ```
  </Tab>

  <Tab title="Cursor / Windsurf">
    Add this to your MCP config:

    ```json theme={null}
    {
      "mcpServers": {
        "okrapdf": {
          "type": "http",
          "url": "https://api.okrapdf.com/mcp"
        }
      }
    }
    ```
  </Tab>

  <Tab title="Legacy bridge">
    For clients that only support stdio:

    ```json theme={null}
    {
      "mcpServers": {
        "okrapdf": {
          "command": "npx",
          "args": ["-y", "mcp-remote", "https://api.okrapdf.com/mcp"]
        }
      }
    }
    ```
  </Tab>
</Tabs>

## What the tools do

| Tool                               | Use it for                                                                                                                                      |
| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `verify_source`                    | Verify a PDF-backed claim, preferably with page text plus bounding-box evidence. Can work from `document_id` or from `pdf_url` plus page hints. |
| `upload_document`                  | Upload a PDF URL or base64 payload for full parse and live viewer polling.                                                                      |
| `resolve_pdf_url`                  | Resolve a public PDF URL through Okra's URL registry before full-document ingest or visual review.                                              |
| `describe_collection`              | Inspect collection metadata, document list, SQLite schema, and query patterns.                                                                  |
| `execute_code`                     | Run JavaScript over `docs.*`, `sql.*`, and `citation.*` for document or collection analysis.                                                    |
| `view_pdf` / `view_document`       | Open the visual MCP App with page previews and bounding-box overlays.                                                                           |
| `interact`                         | Navigate or highlight inside an already-open visual document viewer.                                                                            |
| `review_extraction`                | Open the bbox extraction review workflow with verify and flag controls.                                                                         |
| `view_structured` / `inspect_html` | Open the parsed HTML/PDFQuery inspector MCP App.                                                                                                |
| `render_ui`                        | Query document data and render charts, tables, metrics, proof cards, or dashboards in an MCP App.                                               |
| `create_view`                      | Render model-authored safe component JSON when the model already has the data.                                                                  |
| `draft_workflow`                   | Author a catalog workflow or dynamic agent workflow script using `agent()` / `parallel()` / `pipeline()` / `phase()`.                           |
| `run_workflow`                     | Start a saved workflow and return the run id/status URL.                                                                                        |
| `view_workflow`                    | Inspect a workflow blueprint, readiness, AST, visualization, finite-definition validation, and static agent analysis.                           |
| `view_workflow_run`                | Inspect run status, controller output, per-agent outputs, events, logs, and failures.                                                           |

## Example prompts

```text theme={null}
Upload this PDF and open the visual viewer:
https://www.irs.gov/pub/irs-pdf/fw9.pdf
```

```text theme={null}
Verify that the vendor total is $12,450 on page 2 and show the proof card.
```

```text theme={null}
Describe my earnings collection, then use execute_code to compare revenue by company.
```

```text theme={null}
Render a dashboard of invoice totals by vendor with source citations.
```

```text theme={null}
Draft a dynamic agent workflow that runs text-layer and VLM extraction in parallel, then uses a judge agent to flag discrepancies.
```

## Citation verification modes

`verify_source` defaults to `verification_requirement: "bbox"`. This means Okra only mints a durable proof link when it can resolve page text and bounding-box coordinates.

Use `verification_requirement: "text_match"` only when a deterministic text match is enough and a visual proof link is not required.

## Upload limits and URL caveats

Direct URLs work best for public PDFs, raw GitHub files, arXiv PDFs, and presigned S3/GCS URLs. Sites with anti-bot protection, login walls, JavaScript rendering, or CAPTCHA can block server-side fetches. For app/API integrations, use `POST /v1/documents` multipart upload instead of asking the MCP server to fetch a protected URL.