# MCP tool reference

> All 72 account tools, the scope each one needs, the payload ceilings and the common errors.

`tools/list` returns **only** the tools the presented key's scopes allow. A
key with no write scope cannot see a write tool, let alone call one.

Full argument schemas come back from `tools/list` itself.

## Tools by scope

### No scope required

| Tool | What it does |
| --- | --- |
| `whoami` | Return the identity this API key acts as: your username, display name, plan, and the scopes granted to this key |

### `read:blueprints`

| Tool | What it does |
| --- | --- |
| `get_blueprint` | Fetch one of your blueprints by id or slug: prose files plus every diagram tab's components |
| `get_blueprint_analytics` | Aggregate reach for one blueprint you can edit: human views, unique visitors, traffic-source and referrer breakdowns, crawler/AI-agent traffic, and the helpful/not-helpful tally |
| `get_blueprint_audience` | Report who can currently reach a blueprint you can edit: its visibility, its classification label, and whether a password gate is set |
| `get_blueprint_translation` | Fetch one locale's translation: the translated title and summary, plus the per-stratum name/body overlays |
| `get_portfolio` | Fetch one portfolio by id: its metadata, folder tree, and everything filed in it |
| `get_review_status` | Where a blueprint stands in its team's approval gate, and whether `submit_for_review` would be accepted right now |
| `get_standalone_diagram` | Fetch one standalone diagram in full, including its body |
| `get_stratum` | Fetch one stratum by id: its body plus every secondary tab |
| `get_template` | Fetch one template's metadata and shape: name, description, category, scope, and counts of what the snapshot contains |
| `list_blueprint_locales` | List the languages a blueprint publishes in, with how much of each translation exists |
| `list_blueprint_tags` | List a blueprint's tags, with how each was attached (manual / llm-accepted) and its taxonomy placement |
| `list_blueprints` | List your blueprints, owned and shared with you |
| `list_change_requests` | List the change requests filed against a blueprint you can edit |
| `list_diagram_tabs` | List a blueprint's diagram tabs and the components on each, with ids, kinds and body sizes |
| `list_icon_packs` | List the icon libraries available to you: curated packs, your own uploads, and packs shared by your teams |
| `list_podium_slides` | List every Podium slide on a blueprint, grouped by chapter, with id, label and geometry |
| `list_portfolios` | List your portfolios, with item counts |
| `list_standalone_diagrams` | List standalone diagrams owned by you or by a team/org you belong to |
| `list_strata` | List the strata on a blueprint you can view |
| `list_templates` | List Compendium templates you can see: personal, shared, and Blueprintr defaults |

### `read:vellums`

| Tool | What it does |
| --- | --- |
| `get_vellum` | Fetch one vellum diagram in full, including its `docYaml` body |
| `list_vellums` | List your vellum diagrams: owned, shared via team/org, or granted to you |

### `read:foliums`

| Tool | What it does |
| --- | --- |
| `get_folium` | Fetch one folium: metadata, the full page tree (ids, titles, slugs, resolved URL paths, draft status, body sizes) and its strata index |
| `get_folium_page` | Fetch one folium page in full, including its markdown body |
| `get_folium_stratum` | Fetch one folium-owned stratum in full |
| `list_foliums` | List the foliums you can author, newest-edited first |

### `read:organization`

| Tool | What it does |
| --- | --- |
| `get_org` | Fetch one organisation you belong to, with your role, aggregate counts and your teams inside it |
| `get_team` | Fetch one team by id or slug. Pair a slug with `orgId` when two of your orgs use the same one |
| `list_orgs` | List the organisations you belong to, with your role in each |
| `list_teams` | List the teams you belong to, with your role and the organisation each sits under |

### `search`

| Tool | What it does |
| --- | --- |
| `search_my_content` | Full-text search across the blueprints and docs you can access |

### `write:blueprints`

| Tool | What it does |
| --- | --- |
| `create_blueprint` | Create a new blueprint as a private draft |
| `create_blueprint_from_template` | Create a private draft from a blueprint template you can see |
| `create_diagram_tab` | Add a diagram tab to a blueprint, carrying one component |
| `create_portfolio` | Create a portfolio in a workspace you administer |
| `create_portfolio_folder` | Create a folder inside a portfolio you manage |
| `create_standalone_diagram` | Create a standalone diagram you own |
| `create_stratum` | Add a stratum, optionally bound to a diagram shape so it opens when that shape is clicked |
| `create_stratum_tab` | Add a secondary tab to a stratum |
| `create_template_from_blueprint` | Capture a blueprint as a reusable personal template |
| `file_blueprint` | File a blueprint into a portfolio you manage |
| `publish_blueprint` | Publish one of your standalone draft blueprints |
| `rename_podium_slide` | Change the label of one Podium slide, leaving every other slide untouched |
| `save_blueprint_translation` | Upsert one locale's translation of a blueprint you can edit |
| `set_blueprint_tags` | Replace the whole tag set on a blueprint |
| `unfile_blueprint` | Return a blueprint to its owner's Main portfolio |
| `update_blueprint` | Update one of your **draft** blueprints: title, summary, and/or body |
| `update_diagram_component` | Replace a diagram component's source (diagram YAML/XML, or markdown for a rich component) |
| `update_portfolio` | Rename a portfolio, or change its description |
| `update_standalone_diagram` | Update a standalone diagram's title and/or body |
| `update_stratum` | Update a stratum's name and/or body |
| `update_stratum_tab` | Update a secondary tab's name and/or body |
| `update_template_details` | Rename a template, or change its description or category |

### `write:vellums`

| Tool | What it does |
| --- | --- |
| `create_template_from_vellum` | Capture a vellum as a reusable personal template |
| `create_vellum` | Create a vellum diagram from a `docYaml` body |
| `create_vellum_from_template` | Create a private vellum from a template you can see |
| `file_vellum` | File a vellum into a portfolio you manage |
| `unfile_vellum` | Return a vellum to the Unfiled bucket |
| `update_vellum` | Update a vellum's title, `docYaml` body, visibility and/or tags |

### `write:foliums`

| Tool | What it does |
| --- | --- |
| `create_folium` | Create a folium with a seed Overview page |
| `create_folium_page` | Add a page to a folium's nav tree |
| `create_folium_stratum` | Add a folium-owned stratum, which is what a `stratum:` link inside a folium page opens |
| `move_folium_page` | Reparent and/or reorder one page in the nav tree |
| `update_folium` | Update a folium's title and/or description |
| `update_folium_page` | Update a page's title, description, body, icon or nav placement |
| `update_folium_stratum` | Update a folium stratum's name, body, language hint, icon or folder path |

### `write:sharing`

| Tool | What it does |
| --- | --- |
| `raise_blueprint_classification` | Raise the classification label: public → internal → confidential |
| `restrict_blueprint_audience` | Make a blueprint less visible: public → unlisted → private |

### `write:review`

| Tool | What it does |
| --- | --- |
| `create_change_request` | File a change request against a blueprint you can edit |
| `submit_for_review` | Hand a team-owned draft into its team's approval gate |
| `withdraw_change_request` | Retract an open change request you authored |

## Calling a tool directly

The transport is plain JSON-RPC, so you can test without a client:

```bash
curl -fsS https://blueprintr.io/api/mcp \
  -H "Authorization: Bearer $BLUEPRINTR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"list_blueprints",
                 "arguments":{"status":"draft","limit":10}}}' \
  | jq -r '.result.content[0].text | fromjson'
```

List tools return a `nextCursor`. Pass it back as `cursor` for the next page
rather than raising `limit`: the ceiling is 100, and paging is cheaper than a
retry.

Up to 20 JSON-RPC messages can go in one batch array. Past that the request is
rejected: a single HTTP request clears the rate limiter once, so an uncapped
batch would fan one request out into arbitrarily many tool calls.

## Concurrent writes

`update_vellum` accepts a `baseUpdatedAt`. Send the `updatedAt` you read, and
the write is refused with `STALE_WRITE` if the document moved underneath you.
Re-read, reapply, retry with the new timestamp.

Without it, the write is last-writer-wins. On a document a person also has
open, send it.

## Payload ceilings

| Field | Limit |
| --- | ---: |
| Blueprint title | 500 characters |
| Blueprint summary | 280 characters |
| Blueprint body | 256 KiB |
| Vellum `docYaml` | 1,500,000 characters |
| Vellum title | 200 characters |
| Vellum tags | 20 tags, 1–64 characters each |

## Rate limits

Every window is five minutes.

| Bucket | Limit |
| --- | ---: |
| Requests per IP | 60 |
| Requests per key | 600 |
| Write tool calls per key | 40 |
| JSON-RPC messages per batch | 20 |

Request-level limits return HTTP `429` and JSON-RPC `-32000`. The write bucket
returns a tool error asking you to slow down, so it arrives as a normal
result with `isError: true` rather than as a transport failure.

## Errors

| Symptom | What it means |
| --- | --- |
| Only `whoami` is listed | The key has no other scope. Scopes are fixed at creation, so mint a new key |
| The *documentation* tools are listed | The key was not accepted at all. Check the header is complete, and that the key is not revoked |
| `405` on `GET` | Expected. The optional SSE stream is not enabled; use `POST` |
| "Blueprint not found" | Wrong id, or not reachable by this account. Missing and forbidden return the same message, because telling you which would itself be a disclosure |
| A published blueprint will not update | Writes reach your own drafts only |
| `STALE_WRITE` | Someone else changed the vellum. Re-read and retry |
| A vellum body write is refused | Blueprint-bound vellums are edited through the blueprint; a standalone one needs live collaboration switched off first |
| `429` or `-32000` | Poll less, batch smaller |

Tool failures come back as MCP results with `isError: true` and a readable
message. Only protocol failures use the JSON-RPC `error` object, so a client
that checks only for `error` will read a refused write as a success.