MCP server

Blueprintr exposes a personal MCP server, so an agent can read and author your content directly.

POST https://blueprintr.io/api/mcp
Authorization: Bearer bpk_user_…
Content-Type: application/json

Streamable HTTP, JSON-RPC 2.0, POST only. There is no server→client SSE stream, so a GET returns 405 with a message saying so. That is expected, not a misconfiguration. Every response comes back inline in the POST body, so clients that cannot open the optional stream still work. CORS is open, because agents call cross-origin.

Before you start

Mint a personal key at Dashboard → Settings → API keys & MCP. Keep the default read scopes for a first connection; add a write scope only once you know what the agent needs. See API keys and scopes.

Claude Code

claude mcp add --transport http blueprintr https://blueprintr.io/api/mcp \
  --header "Authorization: Bearer $BLUEPRINTR_API_KEY"

Then run /mcp and confirm blueprintr is connected.

To share the server with a project instead, commit a .mcp.json that reads the key from the environment rather than one with the key in it:

{
  "mcpServers": {
    "blueprintr": {
      "type": "http",
      "url": "https://blueprintr.io/api/mcp",
      "headers": {
        "Authorization": "Bearer ${BLUEPRINTR_API_KEY}"
      }
    }
  }
}

Export BLUEPRINTR_API_KEY before starting Claude Code.

Codex

Codex reads the token from an environment variable rather than storing it:

export BLUEPRINTR_API_KEY='bpk_user_…'
codex mcp add blueprintr \
  --url https://blueprintr.io/api/mcp \
  --bearer-token-env-var BLUEPRINTR_API_KEY
codex mcp list

The variable has to be present whenever Codex starts, so put the export in your shell profile or a direnv file rather than typing it each session.

Cursor

~/.cursor/mcp.json for every project, or .cursor/mcp.json for one:

{
  "mcpServers": {
    "blueprintr": {
      "url": "https://blueprintr.io/api/mcp",
      "headers": {
        "Authorization": "Bearer bpk_user_…"
      }
    }
  }
}

Restart Cursor, then check Settings → Tools & MCP. A project-level file with a key in it must not be committed.

VS Code with Copilot

.vscode/mcp.json. This form prompts for the key instead of storing it, which makes the file safe to commit:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "blueprintr-key",
      "description": "Blueprintr personal API key",
      "password": true
    }
  ],
  "servers": {
    "blueprintr": {
      "type": "http",
      "url": "https://blueprintr.io/api/mcp",
      "headers": {
        "Authorization": "Bearer ${input:blueprintr-key}"
      }
    }
  }
}

Run MCP: List Servers from the command palette, start blueprintr, then use it from Copilot's agent mode.

Claude Desktop

Not yet. Its remote-connector UI accepts authless or OAuth servers, and Blueprintr's personal keys are a static bearer header. claude_desktop_config.json is for local stdio servers, so the remote endpoint does not belong there either.

Use Claude Code, Codex, Cursor or VS Code until Blueprintr offers OAuth for personal MCP connections.

Any other client

Most clients have a generic remote-server form. These are the values:

Field	Value
Name	blueprintr
Transport	Streamable HTTP
URL	https://blueprintr.io/api/mcp
Header name	Authorization
Header value	Bearer bpk_user_…

First calls

Ask the agent for these in order. Each one fails in a different, informative way if the key is wrong:

Use Blueprintr's whoami tool.
List my draft blueprints.
Search my content for "payments".

whoami works with any live key and reports the scopes it has, so a key minted with the wrong ones shows up on the first call. If the client lists only whoami, the key has no other scope. If it lists the documentation tools instead, the key was not accepted at all.

What it will not do

Blueprint writes affect your own drafts only. Published, team-authored and org-authored blueprints are edited in the app.

A second server: your documentation

Everything above is the account server: your content, authenticated as you. A folium also publishes its own read-only MCP server, so an agent can search and read that documentation with no key at all:

https://docs.example.com/foliums/<slug>/mcp

Manage → MCP server on any folium gives you the URL and a ready-made snippet for Claude Code, Cursor and VS Code. The Claude Code one is a single line, with no header:

claude mcp add --transport http my-docs https://docs.example.com/foliums/<slug>/mcp

	Account server	Documentation server
URL	/api/mcp	/foliums/<slug>/mcp
Auth	Personal key, required	None, for public content
Reads	Everything you can see	One folium
Writes	With a write scope	Never

Point a customer's agent at the documentation server and your own at the account server. An organisation key with the mcp scope widens the documentation server to that organisation's private docs.

Where to go next