Napkin as MCP tools
The Napkin MCP server lets an AI assistant make a visual for you directly. You connect it once, sign in with your Napkin account, and the assistant can turn text into a diagram without anyone writing code against the REST API.
It speaks the Model Context Protocol, so any assistant that supports MCP connectors can use it.
The server is live and in beta. The three tools below are what it does today, and we may add to them or change their details while the beta runs, so pin nothing to them that you cannot adjust.
Tell us how it goes at api@napkin.ai, while there is still time for it to change the result.
Connecting
Add Napkin to your assistant as a remote MCP server at:
https://mcp.api.napkin.ai/mcp
Where you put that address depends on the assistant: most call it a connector, a custom integration, or simply an MCP server. The assistant then sends you to Napkin in your browser to approve the connection once, and from then on it has the three tools below.
What your assistant can do
Three tools, which is the whole surface.
create_visual
Turns text into a visual and returns it. The call waits for the generation rather than handing back a job to poll. It can generate one visual or up to four variations.
| Parameter | Meaning |
|---|---|
content | The text to turn into a visual. Required. |
format | svg, png or ppt. Required. |
context | Surrounding text that should inform the visual without appearing in it. |
language | BCP 47 tag of the content language, such as en-US. |
style_id | A built-in style from list_styles or a configured brand style ID. Brand styles cannot be created through MCP. |
visual_query | The kind of layout to look for, such as mindmap or timeline. |
number_of_visuals | How many variations to generate, 1 to 4. |
visual_id | Reuse a returned visual layout with new content. Single visual only; cannot be combined with visual_query. |
color_mode | light, dark or both. |
orientation | auto, horizontal, vertical or square. |
transparent_background | Whether the background is transparent. |
width, height | Pixel size. PNG only. |
visual_query is a preference and may be overridden to fit the content or orientation. Both
visual_query and visual_id require a single visual. Reusing a layout creates a new visual and
spends credits; it does not edit the original visual or a Napkin document.
Generation sometimes takes longer than the call can wait. When that happens MCP returns an isError: true
result whose text still carries the request id and tells your assistant to collect the visual with
get_visual. Do not create the visual again while its outcome is uncertain: the original may already
have been charged, and the API has no idempotency key. The work is not lost: it is still being
generated, and it has already been paid for. An assistant that treats this as a plain failure throws
away a visual you have been charged for.
get_visual
Collects a visual that was still generating when create_visual ran out of time. It takes the
request_id that call gave you.
list_styles
Lists built-in styles, each with the style_id to pass back to create_visual. Custom styles are
not listed; copy their brand ID from the Napkin app. Listing costs nothing.
Signing in
You sign in once, in your browser, the way you would connect any other app. You never paste an API token into your assistant, and your assistant never sees your password.
Under the covers this is OAuth 2.0, and your assistant does the work: it discovers where to send you, sends you to Napkin to approve the connection, and exchanges the result for an access token scoped to your account. The consent screen names the application asking and shows the domain it is served from, which is the one thing an application cannot claim falsely.
Two scopes exist. user identifies your account. generation is what lets the assistant create
visuals and spend your credits.
If you are building the assistant rather than using one, two details matter. Client registration uses
client ID metadata documents rather than Dynamic Client
Registration, so your client_id is the HTTPS URL of a document describing your client, and there is
no registration endpoint to call. Proof keys are required, and only S256 is accepted. A desktop
client can register a loopback redirect without a port, such as http://localhost/callback, and
connect from whatever port the operating system gives it.
What comes back
Visuals come back in the conversation where they fit. SVG arrives as text, images arrive as images.
Successful create_visual and get_visual calls also return structuredContent with request_id,
status, generated_files, and warnings. Each file includes its authenticated download url,
actual visual_id and style_id, and pixel width and height. Each warning carries code and
message; no warnings is an empty array. The same metadata is included as text for clients that do
not read structured results. Inspect it before claiming that a requested brand was applied or all
requested visuals were produced. A refreshed earlier style ID can also raise invalid_style_id, so
use the actual returned style ID as well as the warning. See Styles.
| Limit | |
|---|---|
| One file inline | 4 MiB |
| One answer inline | 8 MiB |
| How long a visual stays available | 30 minutes after the request completes |
Anything larger than the inline budget is returned as a link instead, which your assistant downloads
from the API host with the same credential. Host support for authenticated downloads is needed for
PPT files and oversized outputs. The link expires 30 minutes after the request completes. The
request status and files are also deleted after 30 minutes; later collection answers
request_expired, so collect anything you want to keep within that window.
Credits and failures
Creating a visual spends credits from your Napkin account, at the same rate as the REST API. Listing styles and collecting an already-generated visual cost nothing.
When a generation fails, the tool tells your assistant why, so it can do something sensible rather than guess:
- If the request itself could not produce a visual, it suggests different content.
- If the account is out of credits, or cannot spend in that workspace, it says plainly that retrying will not help, because that is for you to settle rather than something to wait out.
- If the failure is ours, it says rewriting the content will not help and to try again later.
That distinction matters in practice. An assistant told only that something failed will rewrite your prompt and try again, spending credits each time, when the cause had nothing to do with what you asked for.
Skill
The portable napkin-visuals skill is distributed at
service-mcp/skills/napkin-visuals.
A compatible agent can load it from that directory. To install it for Codex, copy the skill folder
into $CODEX_HOME/skills/napkin-visuals (or ~/.codex/skills/napkin-visuals when
CODEX_HOME is unset).
See also
- Introduction — the REST API this is built on.
- Errors, limits and stability — error codes and rate limits in full.
- Styles — what the style catalogue contains.