# MCP server

> Connect Claude Code, Codex, Cursor or any MCP client to your Blueprintr account, with the config for each.

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

![blueprint:josh/connecting-an-ai-agent](https://blueprintr.io/embed/josh/connecting-an-ai-agent?exclude=cmtpw8vmp002alduyez4fwryw&hideTabBar=1#h=620)

```http
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](/foliums/blueprintr-user-guide/developers/api-keys-and-scopes).

## Claude Code

```bash
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:

```json
{
  "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:

```bash
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:

```json
{
  "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:

```json
{
  "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:

```text
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

> [!IMPORTANT]
> There are no tools for deleting or trashing content, changing sharing
> permissions, or reaching account, billing, security or admin settings. The
> server cannot grant another person access to anything. Visibility moves only
> through the constrained publish and audience tools. Those are monotonic:
> they can narrow an audience, never widen it.

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:

```bash
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

> [!TILES 2]
>
> === [Tool reference](/foliums/blueprintr-user-guide/developers/mcp-tool-reference)
>
> All 72 tools, the scope each needs, and the limits that apply.
>
> === [Documentation CLI](/foliums/blueprintr-user-guide/foliums/docs-cli)
>
> For folium authoring from a text editor, use this rather than MCP.