Connect an MCP Client to Blink PDF

The Blink PDF MCP server 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.
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.

Get credentials

API key (IDEs and CLIs)

Create a key in the API Keys section of your dashboard 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 <token>. Request offline_access only when you need refresh tokens. Full agent-oriented steps: auth.md.

Configure your client

Pick your agent. The examples below use an API key header path (the common IDE setup).

Claude Code
Codex
Other clients

Add the server over HTTP transport:

Production

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:

.mcp.json

{
  "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.)

Add server

codex mcp add blinkpdf \
  --url https://mcp.blinkpdf.io/mcp \
  --bearer-token-env-var BLINKPDF_API_KEY

Export API key

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:

config.toml (bearer_token_env_var)

[mcp_servers.blinkpdf]
url = "https://mcp.blinkpdf.io/mcp"
bearer_token_env_var = "BLINKPDF_API_KEY"
tool_timeout_sec = 600

config.toml (inline Authorization)

[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, 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.

Render your first PDF

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 (list_themes), stage local images for blink://asset/<id> references (upload_image), and dry-run a request (validate_render_pdf) before rendering. See the MCP server overview 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. Agents that discover skills via /.well-known/agent-skills/ can load the published render-pdf skill before calling tools.

Get Started

Core Concepts

Guides

MCP Server

Configuration

Plans & Limits

Help

Connect an MCP Client to Blink PDF

API key (IDEs and CLIs)

OAuth (remote connectors)

Troubleshooting

References

​API key (IDEs and CLIs)

​OAuth (remote connectors)

​Troubleshooting

​References

API key (IDEs and CLIs)

OAuth (remote connectors)

Troubleshooting

References