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 Markdown or fill a form. One paste of the snippet below uses the same bp_ key as REST POST /v1/render. The tool list includes inspect_form and fill_form next to render_pdf. Do not mint a fill key. Do not request pdf:fill. 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). Each snippet is one paste: same endpoint, same bp_ key, and after you connect the tool list includes inspect_form and fill_form next to render_pdf. No extra OAuth step beyond what render already uses.

Cursor
Claude Code
Codex
Other clients

Paste this into .cursor/mcp.json in your project, or ~/.cursor/mcp.json for every workspace. That is the whole connection.

.cursor/mcp.json

{
  "mcpServers": {
    "blinkpdf": {
      "url": "https://mcp.blinkpdf.io/mcp",
      "headers": { "Authorization": "Bearer ${env:BLINKPDF_API_KEY}" }
    }
  }
}

Export API key

export BLINKPDF_API_KEY="bp_YOUR_API_KEY"

If Cursor does not expand ${env:BLINKPDF_API_KEY} in remote headers, paste the Bearer value instead — still one server, still the same bp_ key:

.cursor/mcp.json (inline Authorization)

{
  "mcpServers": {
    "blinkpdf": {
      "url": "https://mcp.blinkpdf.io/mcp",
      "headers": { "Authorization": "Bearer bp_YOUR_API_KEY" }
    }
  }
}

Open Customize (or Cursor Settings → MCP), enable blinkpdf, and confirm the tool list includes inspect_form and fill_form next to render_pdf. Same bp_ key as render_pdf. Do not add a second server, a fill key, or a pdf:fill scope.

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. One paste — the same bp_ key lists inspect_form and fill_form next to render_pdf:

.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. Confirm inspect_form and fill_form appear with render_pdf.

Blink PDF is a remote HTTP server — add it with codex mcp add --url and read the API key from an environment variable. One paste; the same bp_ key lists inspect_form and fill_form next to render_pdf. (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. Confirm inspect_form and fill_form appear with render_pdf.

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. Cursor reads .cursor/mcp.json (see the Cursor tab).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.

Render and fill 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 or fill completes.

Render or fill

Once connected, confirm the tool list includes render_pdf, inspect_form, and fill_form. Then ask in plain language:

“Render this README as a PDF and give me the download link.”
“Inspect this form, fill givenName with Ada and agree with true, and give me the download link.”
“Turn the Markdown report below into a styled PDF.”

The fill loop is inspect_form → validate_fill → fill_form — see MCP fill. The agent can also keep a file (persist: true on render_pdf or fill_form, or persist_pdf afterward), list or delete stored PDFs (list_pdfs, delete_pdf), list 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.Agents that load skills from /.well-known/agent-skills/ can read render-pdf and fill-form. Those artifacts name the tools; they still use this same server paste and the same bp_ key.

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). Same `bp_` key as render — do not mint a fill key.
Fill tools missing after paste	You connected to the endpoint; `inspect_form` and `fill_form` ship on that same server. Re-enable blinkpdf and refresh the tool list. Do not add a second MCP server or a `pdf:fill` scope.
Timeout	`render_pdf` and `fill_form` can be 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.
Cursor header not sent	Set `BLINKPDF_API_KEY` in the environment Cursor inherits, or paste `Authorization: Bearer bp_…` in `headers`. Same key as render.
`402`	Plan limit reached — do not retry; raise the spend cap or upgrade the plan.
`persistent_pdf_limit`	Kept-file cap reached — delete one with `delete_pdf` or upgrade. The file was not saved as 24-hour.
`persist_pdf_gone`	The 24-hour file expired before `persist_pdf`. Re-render with `persist: true` if you still have the source.
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.

References

Blink PDF auth.md
Cursor — MCP
Claude Code — MCP
Codex — MCP
MCP transports
fill-form skill (inspect_form → fill_form)
render-pdf skill

Get Started

Fill a form

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