MCP Server

Connect an AI assistant or an agent runtime to Lolly and it can make finished, on-brand files for you: a QR code, a badge, a chart or a slide deck, as SVG, PNG, PDF and more. Every answer comes with an editable link, so you can open the result in Lolly and adjust it by hand.

The quickest start needs no account. In Claude Code, run:

claude mcp add --transport http lolly https://lolly.tools/api/mcp

Then ask: "Use Lolly to make a QR code for https://example.com as an SVG."

Behind that request the agent lists the tools, reads one tool's inputs, renders it and hands you the file. Tools are data, so a new tool reaches a server as a catalog update, with no change to the server's code.

Each server draws with the design system of its own content profile. The public server on lolly.tools uses Lolly Demo. Read the lolly://design-context resource to see which design system a server uses, with its colours, type, logos and house rules.

AI agents compares this server with the other ways an agent can drive Lolly. This page is the reference for the server itself.

Choose an endpoint

Every endpoint offers the same twenty-two tools. They differ in who can connect and which formats they can make, because only some run a headless browser.

Start with the open endpoint: it needs no setup and covers every SVG-native tool. Tools laid out in HTML, such as design and chart, draw in the browser tier, so rendering or looking at them needs the full endpoint or your own machine. So does print PDF. Large files and heavy automation also belong on your own machine.

A render on any endpoint runs the same render path a person's export runs. The server honours the full parameter contract (width, height, unit, dpi, colour profile, PDF password and, for the motion formats, fps, seconds, wait, codec and vq), and it never watermarks or embeds anything a person's own download would not. The same path and settings do not mean the same bytes for every format; see how far byte-identical output goes.

Connect a client

The open endpoint (no token)

Point any MCP client that speaks Streamable HTTP at https://lolly.tools/api/mcp. There is nothing to sign in to:

{
  "mcpServers": {
    "lolly": { "type": "http", "url": "https://lolly.tools/api/mcp" }
  }
}

In Claude Code the same connection is one command:

claude mcp add --transport http lolly https://lolly.tools/api/mcp

In a hosted assistant, add a custom connector with that URL and leave the OAuth fields blank. A quick check with curl (expect a JSON list of the twenty-two tools):

curl -s -X POST https://lolly.tools/api/mcp \
  -H "content-type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

The full endpoint (access token)

mcp.lolly.tools authenticates against a shared access token, which your Lolly operator holds. The token is never printed in a link or a log.

As a custom connector (OAuth). The full endpoint is a stateless OAuth 2.1 authorization server, so it works with any MCP client that supports custom connectors:

Then ask the agent to "list the Lolly tools" or "render the wordmark tool as a PNG."

With a bearer token (CLI or any HTTP client). The full endpoint also accepts the raw token, so scripted clients skip the OAuth steps. Most MCP clients take a config entry like:

{
  "mcpServers": {
    "lolly": {
      "type": "http",
      "url": "https://mcp.lolly.tools/mcp",
      "headers": { "Authorization": "Bearer <your-access-token>" }
    }
  }
}

A quick check with curl (expect a JSON list of the twenty-two tools, plus the files_* tools when the connection is scoped; no token returns 401):

curl -s -X POST https://mcp.lolly.tools/mcp \
  -H "authorization: Bearer <your-access-token>" \
  -H "content-type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Install Lolly in ChatGPT

ChatGPT connects to Lolly through a plugin, which lets it join a document someone invites it into. Pasting an invitation into a chat cannot install tools, so install the plugin first.

Open Plugins in ChatGPT, choose Create custom MCP server, name the plugin Lolly and set the server URL to https://lolly.tools/api/mcp/agents. Choose No authentication, review the connection notice and create the plugin. Install the resulting plugin, then enable Lolly in your conversation. Account and workspace policies decide whether custom MCP connections are available. See OpenAI's connection guide.

Then copy a fresh invitation from Share in the open document and give it to ChatGPT. Agents in an open document covers the invitation, what the agent can do and how to pause or disconnect the agent.

The installed plugin has no account-wide credential: each invitation selects its instance, document and permissions. It works with public HTTPS Lolly relays on any domain, including lolly.ing. Calls to private networks and local addresses need the local MCP server instead. Directory publication is separate from installing a custom MCP server: Lolly's stable plugin identity is on lolly.tools, and a document invitation selects the instance where the work happens.

On your own machine

From a checkout, pnpm run mcp starts the server over stdio, with no token. The local server lists the twenty-two tools, the six files_* tools and the nine live tools that join an open document (Agents in an open document). pnpm run mcp:http runs the long-lived HTTP service instead. Run the server yourself covers hosting one for other people.

How an agent uses the server

The server's own prompts walk an agent through the same order:

Every input and export control is a URL parameter, defined by URL mode and Reserved URL parameters. The MCP query argument, a share link, the CLI's --flag=value pairs and the hot-link render URL are one contract under four transports, so an agent that has learnt the table has learnt all four. The reserved parameters an agent reaches for most are format, width, height, unit and dpi, profile, password, bleed and marks, the provenance switches (c2pa, imprint, durable, meta), _madewith (the design-system record, on unless _madewith=0), hdr and depth, cuts, s, lang, emoji and emojifx, plus fps, seconds, wait, codec and vq for the motion formats.

Formats are per tool: you can only ask for one the tool declares, and lolly_describe_tool lists them. The call is the same whether you ask a QR tool for svg or an animated tool for mp4; the server decides how to produce the file. Every format Lolly can open and make lists them all. To ask whether Lolly reads or writes a format, call lolly_list_tools with a format filter, or fetch /info/capabilities.json. There is also a page for every format at /info/formats/<token>/ and one for each common conversion at /info/convert/<in>-to-<out>/.

The twenty-two tools

Discover and describe:

Check and inspect a document before you spend a render:

Explain the design system:

Build a link or render:

Look at a render in its own coordinates:

On-device file utilities (bytes in, bytes out):

On an authenticated connection with a file scope, six more tools appear for importing a private file once and working on its handle: files_import, files_list, files_download, files_convert, files_report and files_delete.

Recipes

Edit a Design document by layer id

For Design, start from templateId plus an optional presetId and a small set of input overrides; lolly_describe_tool lists those starting points. The same arguments work with validate, compile, inspect, measure, URL building and render. Inspect the template once to find its stable layer ids, then send layerPatches: [{ "id": "s1title", "set": { "text": "Your title" } }] to replace content without resending layer geometry. An agent can start from a slide deck or a square poster without inventing raw coordinates.

Use layerOperations to change the layer set itself. It supports strict stable-id add, duplicate, remove, reparent and reorder operations. Reorder anchors must be siblings. Reparent keeps the layer's geometry and accepts a destination artboardId (null means the pasteboard), plus an optional destination sibling anchor. Every duplicate takes an explicit newId; duplicating a non-empty artboard also needs a complete childIds map. Removing a non-empty artboard needs cascade: true. Operations run before layerPatches, so a newly created or moved layer can be patched in the same call:

{
  "toolId": "design",
  "templateId": "slide-deck",
  "layerOperations": [
    {
      "op": "add",
      "layer": { "id": "s1-kicker", "kind": "text", "frame": "slide1", "text": "Draft" },
      "afterId": "s1title"
    }
  ],
  "layerPatches": [
    { "id": "s1-kicker", "set": { "text": "Agent-added context" } }
  ]
}

Rebrand: renovate a deck, in stages

lolly_rebrand reads a .pptx you supply and turns it into this server's design system: colours, fonts and logo snapped to the system, decoration and page furniture pulled out. It runs the same node pipeline as lolly rebrand on the CLI, so a plan made on one compiles on the other, as long as both read the same design system; otherwise compile refuses it with plan.design-system-mismatch. It runs no browser and needs neither endpoint's browser tier, so it is available wherever the MCP server runs.

On mcp.lolly.tools and lolly.tools/api/mcp, calling lolly_rebrand uploads your deck to Lolly's server. It is processed in memory for that call only and not kept. Each endpoint takes a deck of up to about 3.2 MiB, because the deck and its base64 encoding must fit one request of up to 4.5 MB (LOLLY_MCP_REQUEST_MAX_BYTES). For a larger deck, run lolly rebrand on the CLI or point an agent at a local MCP server. lolly_read, lolly_check and lolly_compose also send a deck you pass them to the server.

The agent skill's Rebrand reference walks an agent through the stages and the plan's fields.

Read a deck, check a recreation

When an agent rebuilds a deck in Design rather than renovating it with lolly_rebrand, three calls carry the work:

lolly_read takes {file} and returns the content inventory (schema content-inventory-v1) with counts per kind: text in reading order with roles and runs, speaker notes with paragraphs and line breaks kept apart, pictures by content hash with placement and crop, tables and charts as data, plus the class of every object. An inventory over 128 KB comes back as an embedded JSON resource instead of inside the structured result. Pictures come back as facts (hash, type, size, placement); media: "inline" also returns the bytes of each distinct picture, one embedded resource each. No text recognition runs, so a slide that is one picture of a slide reads as a picture (ocr is false). The same reader as lolly read --json.

lolly_check returns the same report lolly check --json writes (schema check-report-v1): five families (structure, render, brand, verify, fidelity), each ran, skipped, unavailable or failed with a reason, and one findings list. Each finding has a stable code, a severity, the layerId where there is one, the message the app shows and a fix where one is safe. Findings are data, so the call is a tool error only when the request or the file cannot be read.

The render family (clipped text, contrast and font coverage on the painted page, with the document's pictures painted) needs the browser tier. A hosted server runs it only where it has a browser and a web shell to drive: the browser image with LOLLY_WEB_BASE set. On lolly.tools/api/mcp, which has no browser, it reports unavailable and the other families still run. Verify runs with text recognition off on every server. On a hosted server the file and the source travel in one request, so pass the lolly_read inventory rather than the source deck there.

Compose, measure and package a Design document

Between the read and the check, the agent writes the Design document. For slides, start with lolly_compose: it lays each slide out from an archetype of the design system's slide master, with the master's margins, type, furniture and bindings. Because composed slides keep their master bindings, lolly_check judges them by the master's house rules, and their PowerPoint export has real slide layouts and placeholders.

A spec gives an archetype per slide and fills its slots, by text or by from an inventory object. source on a slide carries that slide's notes. join on a slot ({from, join: ": "}) runs a heading's lines into one. cells, ground, furniture, emphasis, case, under and over cover the rest. themes: ["light", "dark"] on the spec makes one document that serves both themes: logo furniture as <id>?theme=auto, and the master's token colours and the under and over token references stored as literals plus links. furniture, emphasis and case at the top of the spec are deck defaults that each slide merges over. The schema is https://lolly.tools/schemas/design-compose-v1.schema.json, described in the agent skill's Design reference.

The result is the document, a report of what each slide filled, dropped and clipped, the edits to give lolly_check (each with a generic reason to replace) and the pictures it names. A hosted server receives a deck passed as source; pass the lolly_read inventory there instead.

For what no archetype holds (a slide's under and over rows) and for slides written by hand, rows may carry authoring keys, which all start with $: $in gives a layer's position relative to its artboard, $style sets its text by a style from the design brief (title, subtitle, body, caption, label, quote, number, attribution) or from $styles beside boxes, $points and $d draw a path in px, and $stack, $grid and $table lay out repeated rows. Every tool that takes a Design source lowers them first, to ordinary layers in global canvas coordinates with every text field written out: in inputs.boxes, in an add operation's layer and in a patch's set. They are never stored. A key that cannot be lowered is an error with the JSON pointer of the key, and lolly_check reports it as a design.authoring.invalid finding. lolly_compile and lolly_validate return any notes the lowering made under authoring. The keys are described in the agent skill's Design reference, and their schema is https://lolly.tools/schemas/design-authoring-v1.schema.json.

lolly_measure_text answers where a text box's lines break before it is placed, with the faces the canvas loads. A line marked nearEdge is within a few px of breaking another way, so widen that box rather than trust the fit. lolly_package then writes the .lolly a person opens in the app. On a hosted server the pictures and the source travel in one request, and the .lolly comes back in one answer (at most 4.4 MB on a serverless deployment), so package a large deck with lolly package on the CLI.

Redaction needs the full endpoint

lolly_redact rebuilds real pixels (a canvas for images, a page render for PDFs), which the browser-free tier cannot do. On the full endpoint it runs in the same browser path a person clicks in the app, including the tool's own export gate. On the open endpoint it returns an error saying the browser tier is not available there, rather than handing back a file that was never redacted. lolly_transform behaves the same way for any utility that rebuilds pixels; the metadata-only utilities (strip-data, compress-pdf) still run browser-free.

What a render records

The design system and colourway. A render records the design system and colourway that drew the file, in its metadata and its Content Credential, as an export from the app does. The result reads the delivered bytes back and prints the words the file carries, such as Recorded the design system: Lolly Demo · Colourway: Beach. Pass madeWith: false to lolly_render or lolly_build_url to leave the record out; the link then carries _madewith=0, so the file and the link agree.

Songs. A video or audio file that plays a rondocode song records each song in its Content Credentials: its name, a hash of its source and how Lolly's sandbox rendered the song. The result reads the delivered bytes back and states, on a Songs: line, which songs the credential records and any it does not. lolly_transform adds no credential, so its result says the file records none of its songs.

Emoji: name the set you want drawn

Emoji in a render are drawn from a set somebody chose, never from the machine the server happens to run on. lolly_render and lolly_build_url both take two optional arguments for that choice and read them the same way, so a link and the file it renders agree:

emojistyle adds the exact style snapshot, including checksums, ordered fallbacks and palette. All three use the reserved URL parameters of the same name, so the same strings work in a share link, as lolly --emoji=… --emojifx=… on the CLI and here. They travel in the link either call returns, so a person who opens the link sees the artwork the agent rendered.

Call lolly_describe_tool first and read emojiSets: one row per registered set with its id@version, label, glyph count and licence. Choosing a set is choosing a licence, which is why the licence is in the list. A set nobody registers comes back as a usage error listing the ones that are, rather than a picture that arrives without the artwork you asked for.

• With no emoji argument, every emoji draws as a neutral placeholder. Nothing falls back to the operating system's emoji font, on any surface.
• Simple SVG text uses shaped outlines and pack artwork. Unsupported positioning, bidi or missing fonts produce a neutral placeholder with a layout diagnostic. emojifx with no emoji picks a treatment with no artwork to treat, and is reported as a warning.
• The sources are recorded. A render that placed pack artwork reports the pack's credit and licence in its Rights: line, and writes one Content Credential source per distinct glyph where the format can carry one. A browser-tier render establishes the same census on the server, so a PDF or an MP4 records its sources too.

Resources and prompts

Agents should not guess asset ids or brand colours. Alongside the tools, the server exposes read-only MCP resources. Read lolly://skill first:

The intended pairing: read lolly://assets once, then pass a real id to any asset-typed input in lolly_render.

The server also publishes MCP prompts, for clients that show them as slash commands or quick actions:

• create-branded-asset, the generic guided workflow: give it a plain-language brief (and optionally a format) and it walks the agent through picking a tool, reading its schema, rendering and sharing the editable link.
• One prompt per featured tool, named by tool id and built from the live catalog at request time. Its arguments are the tool's inputs (required ones first), its description is the tool's blurb and its message includes the tool's example looks. Nothing is hardcoded, so a newly featured tool gets a prompt automatically, and a pinned prompt keeps working even if the tool later leaves the featured set (only the listing is curated).

Hot-link render URLs

Alongside the MCP endpoints, a deployment can answer the canonical embed URL directly:

GET https://<host>/tool/<tool-id>.<ext>?<inputs>

This is the raw render URL lolly_build_url returns. Drop it into a README, a wiki, a Notion page or a dashboard as an <img src> and it serves real bytes, with no token. The route is per deployment, and it is live on lolly.tools.

A GET's query string ends up in the host's access logs, and a link's inputs can carry personal data, so give a hot-link URL only what you would put on a public page. Fetching one sends the server nothing but what is written in the URL: your on-device documents, sessions and uploads can never appear in one. The privacy policy says what the host keeps.

Its scope is narrow:

• No auth, no accounts, no state. It renders public tool and catalog data only, and nothing is stored per request.
• Official and community tools only. Anything else is a 404.
• Browser-free formats only: svg, emf, eps, eps-cmyk, dxf, exr, hdr, penpot, html, md, txt, json, csv, ics, vcf, plus png for SVG-native tools such as qr-code. A format that needs the browser tier returns a 400; use lolly_render or the app for those.
• Content Credentials are off here, because each signing changes the bytes. Public calendar files use the catalog's build time for DTSTAMP, and an empty Calendar start date uses that build's date at 09:00, so set the event date explicitly when sharing a calendar link. Authenticated lolly_render and local exports keep their usual export behaviour.
• Rate-limited per address, against the same daily budget as the open MCP endpoint. A png is capped at 2048 x 2048 pixels of area.
• Themes. _themes, the theme per token group as JSON (_themes={"":"dark"}), renders a tool this route can draw, such as qr-code, with its token colours in that theme. A value that is not such JSON is a 400, and a choice the design system does not declare draws that group's default theme with no warning. Design needs the browser tier, so this route refuses a Design document in any theme; export one in each theme with lolly run <file.lolly> --themes=light,dark on the CLI.
• Canonical URLs. Parameters are sorted and unused transport parameters are removed with a 308 redirect. A packed z= stays packed with its original encoded bytes; the redirect never expands a large document into the URL.
• noindex. Search engines do not index your renders.

The route's parameters, refusals and headers are described in OpenAPI 3.1 at /openapi.json. An operator switches the route off with LOLLY_DISABLE_RENDER_GET=1, and every such URL then returns 404.

Authentication and security

• Open only when an operator chooses. With no token configured the endpoint returns 401, so a missing setting never opens a server by accident. An operator opens one by setting LOLLY_MCP_ALLOW_ANONYMOUS=1, as lolly.tools does for lolly.tools/api/mcp. An open endpoint serves no OAuth routes, and it limits calls by the caller's address, so an invented Authorization header buys no extra calls.
• A known worst case. A hosted endpoint counts the CPU time it uses and the bytes it sends per UTC day, and refuses work once either total reaches its ceiling. Budgets and rate limits has the settings.
• Stateless OAuth 2.1. The client registration, authorization code and access and refresh tokens are all short-lived signed values, verified with a shared secret on each call; nothing is stored on the server. PKCE (S256) protects the flow, so a captured link cannot be replayed.
• The token stays out of band. It is the bearer for scripted clients and the passphrase on the consent page. It never appears in a render URL or a log line.

The MCP server has no persistent render history. For retained render jobs and batches, retry and cancellation, governed delivery and audit records, an organisation can run Lolly Work, which has its own lw client, HTTP API, authentication and permissions; see Organisation jobs. Connecting an agent to this server does not grant access to a Lolly Work catalog or apply that organisation's policy.

Run the server yourself

The full endpoint is the one part of Lolly that runs as a server-side add-on rather than on the device. Producing the full format range means driving a headless browser against a built web shell, so it runs as a hosted service (a container or a worker), not offline or at the edge. The on-device shells, the web app, desktop, mobile and the CLI, remain the offline and air-gapped path.

You can still run the full server yourself, fully air-gapped included, as a container that ships the scoped Chromium and a prebuilt web shell. See the Build Guide and the deployment notes in services/mcp/. pnpm run mcp:http runs the long-lived HTTP service from a checkout.

Private download links for large results

On a self-hosted, authenticated HTTP gateway, an operator can return large files as private download links instead of inline base64. Files over 1 MiB that a tool returns become MCP resource_link blocks. Download the link with the same MCP bearer used for the tool request. The link expires after five minutes, and a process restart discards the download. A copied link without that bearer grants no access. Store the downloaded file, and keep temporary dt= URLs out of documents, packs and asset references.

Budgets and rate limits

Caching

The agent relay that lets an agent join an open document runs from the same service; Run a document relay covers its setup.