> ## Documentation Index > Fetch the complete documentation index at: https://docs.blinkpdf.io/llms.txt > Use this file to discover all available pages before exploring further. # Connect an MCP Client to Blink PDF > Add the Blink PDF MCP server to Claude Code, Codex, or any MCP client in three steps — create a key, configure the client, render your first PDF. The Blink PDF [MCP server](/mcp/overview) is a hosted **Streamable HTTP** endpoint at `https://mcp.blinkpdf.io/mcp`. There's nothing to install — authenticate, point your client at the endpoint, and your agent can render PDFs. Choose one auth path: * **OAuth 2.1 + PKCE** — preferred for remote connectors that support MCP OAuth. Resource `https://mcp.blinkpdf.io/mcp`, authorization server `https://identity.blinkpdf.io`, scopes `pdf:render` and optional `offline_access`. Discovery lives at `https://mcp.blinkpdf.io/auth.md` and the `/.well-known/*` URLs listed in the [MCP overview](/mcp/overview#auth-and-discovery). * **API key** — same `bp_*` keys as the REST API, for IDEs and clients that only support static headers. MCP forwards the key to REST, which remains the authority for limits and billing. ### API key (IDEs and CLIs) Create a key in the **API Keys** section of [your dashboard](https://app.blinkpdf.io/login) if you don't have one yet. Present the key with either header — `Authorization` is preferred: | Priority | Header | | --------- | --------------------------------------- | | Preferred | `Authorization: Bearer bp_YOUR_API_KEY` | | Fallback | `x-api-key: bp_YOUR_API_KEY` | Never commit the secret. Reference it through an environment variable in your client config, as shown below. ### OAuth (remote connectors) If your client supports remote MCP OAuth, register against `https://identity.blinkpdf.io` (dynamic client registration where available), open the consent screen, and present the access token as `Authorization: Bearer `. Request `offline_access` only when you need refresh tokens. Full agent-oriented steps: [auth.md](https://mcp.blinkpdf.io/auth.md). Pick your agent. The examples below use an **API key** header path (the common IDE setup). Add the server over HTTP transport: ```bash Production theme={null} claude mcp add --transport http blinkpdf https://mcp.blinkpdf.io/mcp \ --header "Authorization: Bearer bp_YOUR_API_KEY" ``` Or declare it in `.mcp.json`, reading the key from an environment variable: ```json .mcp.json theme={null} { "mcpServers": { "blinkpdf": { "type": "http", "url": "https://mcp.blinkpdf.io/mcp", "headers": { "Authorization": "Bearer ${BLINKPDF_API_KEY}" }, "timeout": 600000 } } } ``` Verify with `claude mcp list` or the `/mcp` command inside Claude Code. Blink PDF is a remote HTTP server — add it with `codex mcp add --url` and read the API key from an environment variable. (This path uses a static Bearer token: put only the `bp_*` secret in the env var. Separate remote-connector OAuth is documented in [auth.md](https://mcp.blinkpdf.io/auth.md).) ```bash Add server theme={null} codex mcp add blinkpdf \ --url https://mcp.blinkpdf.io/mcp \ --bearer-token-env-var BLINKPDF_API_KEY ``` ```bash Export API key theme={null} export BLINKPDF_API_KEY="bp_YOUR_API_KEY" ``` Export **only the token** (no `Bearer ` prefix). Codex adds the `Bearer` prefix itself from `bearer_token_env_var` — including it in the value breaks auth. Or configure it manually in `config.toml`: ```toml config.toml (bearer_token_env_var) theme={null} [mcp_servers.blinkpdf] url = "https://mcp.blinkpdf.io/mcp" bearer_token_env_var = "BLINKPDF_API_KEY" tool_timeout_sec = 600 ``` ```toml config.toml (inline Authorization) theme={null} [mcp_servers.blinkpdf] url = "https://mcp.blinkpdf.io/mcp" http_headers = { Authorization = "Bearer bp_YOUR_API_KEY" } tool_timeout_sec = 600 ``` Verify in the TUI with `/mcp`, or start a new `codex` session. **stdio-only clients** (clients that don't support remote HTTP servers) connect through an HTTP→stdio bridge such as [`mcp-remote`](https://github.com/geelen/mcp-remote), pointed at `https://mcp.blinkpdf.io/mcp` with the same auth headers. The `.mcp.json` block from the Claude Code tab works for any client that reads that format. **Local development** — if you're running the Blink PDF stack yourself, run BFF + REST with `DATABASE_URL` set (auth on) and the MCP app with `REST_BASE_URL` pointing at REST and R2 configured. The default local endpoint is `http://localhost:8082/mcp` (the port follows `PORT` in `apps/mcp/.env`). Use the same `Bearer bp_*` header. Rendering can take several seconds. Set a generous tool timeout — `timeout: 600000` (ms) in Claude Code, `tool_timeout_sec = 600` in Codex. The client defaults (\~60s) can fire before a large render completes. Once connected, just ask your agent in plain language — it calls `render_pdf` and hands back a download link: * *"Render this README as a PDF and give me the download link."* * *"Turn the Markdown report below into a styled PDF."* * *"Generate an invoice PDF from this Markdown table."* The agent can also list the available [themes](/configuration/themes) (`list_themes`), stage local images for `blink://asset/` references (`upload_image`), and dry-run a request (`validate_render_pdf`) before rendering. See the [MCP server overview](/mcp/overview#tools) for the full tool set. ## Troubleshooting | Symptom | Likely cause | | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `401` on a tool call | Invalid/revoked API key, missing `Authorization` header, or expired OAuth access token (refresh or re-consent). | | Timeout | `render_pdf` is slow — raise the client timeout (`timeout` ms in Claude Code, `tool_timeout_sec` in Codex) to ≥ 600s. | | Codex auth fails | `BLINKPDF_API_KEY` must contain **only** the `bp_…` token — Codex adds `Bearer` itself; don't include it in the value. | | `402` | Plan limit reached — **do not retry**; raise the spend cap or upgrade the plan. | | Failure reported *after* render looked OK | A self-hosted REST running without auth/DB. The MCP server requires REST identity headers (`x-blinkpdf-account`); never front the MCP with an auth-disabled REST. | For what a successful call returns and how download links expire, see the [MCP server overview](/mcp/overview). Agents that discover skills via `/.well-known/agent-skills/` can load the published `render-pdf` skill before calling tools. ## References * [Blink PDF auth.md](https://mcp.blinkpdf.io/auth.md) * [Claude Code — MCP](https://code.claude.com/docs/en/mcp) * [Codex — MCP](https://developers.openai.com/codex/mcp) * [MCP transports](https://modelcontextprotocol.io/docs/concepts/transports)