Skip to Content
MCP Server

MCP Server

oJo ships an official Model Context Protocol  server, so an AI agent can design and render images and PDFs directly instead of you writing HTTP calls on its behalf. There are two ways to connect it:

  • Remote (recommended). Add https://mcp.ojo.so/mcp to your client and sign in with your oJo account. No API key, nothing to install.
  • Local. The npm package @ojodotso/mcp-server runs on your machine with an API key. Use it for CI, headless machines, clients without OAuth sign-in, or to try previews without an account.

The point of using it over the raw API is the design loop: an agent can iterate on a design at full resolution for free, and spend a credit only on the frame that is actually right.

Connect

No account yet? Signing in creates one, with 30 free credits for 30 days, no card. Previews are free; a PNG render costs 1 credit.

Go to Customize → Connectors → Add custom connector, paste https://mcp.ojo.so/mcp, then sign in. Free plans get one custom connector. On Team and Enterprise plans, an owner adds it under Organization settings → Connectors, and members then connect it.

Run it locally (npm)

Use the local server when your client can’t sign in through a browser (CI, headless machines), or to try previews without an account.

No account needed to try it. Started without OJO_API_KEY, the server runs in preview-only mode: create_preview_link renders your HTML into a live, full-resolution preview, free and unlimited. Add a key from API settings  when you want a hosted PNG URL or reusable templates.

Install

Requires Node.js 20 or newer. You do not need to install anything by hand — npx fetches the package on first run.

claude mcp add ojo -s user -e OJO_API_KEY=<your API key> -- npx -y @ojodotso/mcp-server

-s user makes the server available in all your projects; drop it to scope the server to the current project only. To share it with your team through version control, use -s project — that writes to .mcp.json, so reference the key as ${OJO_API_KEY} and keep the real value in your environment.

Restart your client after adding the server. With a key it lists eight oJo tools; without one it lists only create_preview_link.

Environment variables

VariableRequiredDefaultDescription
OJO_API_KEYNo—Your oJo API key. Without it the server starts in preview-only mode and registers only create_preview_link.
OJO_API_BASE_URLNohttps://api.ojo.so/v1Point the server at a different oJo API — see Self Hosting.
OJO_WEB_BASE_URLNohttps://ojo.soBase URL used to build preview links. Change it if you serve the oJo web app from your own domain.

OJO_API_BASE_URL decides where your API key is sent. Only point it at a host you control.

The design loop

Rendering an image costs a credit; previewing one does not. The tools are built around that asymmetry, and an agent using them well will spend exactly one credit per finished image no matter how many revisions it took.

1. Draft the HTML

The agent writes plain HTML with inline CSS, using {{variable}} placeholders wherever the content should be swappable. Google Fonts and other https: resources work.

2. Preview it — free, unlimited

create_preview_link returns a URL that renders the draft live, at full resolution, through the same engine that produces the final PNG:

{ "html": "<div style=\"...\"><h1>{{title}}</h1></div>", "variables": { "title": "Preview links, zero credits" }, "viewportWidth": 1200, "viewportHeight": 630 }
https://ojo.so/preview#draft=H4sIAAAAAAAAA5VW227jNhD9FYJBuhtAkilZdmTK2Rb...

The draft is compressed into the URL fragment, so it never reaches a server and nothing is stored. From here you have two options, and both are free:

  • The agent checks its own work — open the link in a headless browser and screenshot the iframe[title="oJo draft preview"] element. Give web fonts a moment to load before capturing.
  • A human checks it — paste the link into a message. Whoever opens it sees exactly what the render will produce, with no oJo account needed.

Fix what’s wrong, call create_preview_link again, repeat. Still zero credits.

3. Render or save it

Once the design is right, spend the credit — or don’t spend one at all:

  • generate_image_from_html renders the final PNG and returns its public URL. 1 credit.
  • create_template saves the HTML as a reusable template instead. No credit. Later, generate_image_from_template renders it with per-render values, one credit each.

The generate tools accept inspect: true, which attaches a 512px-wide thumbnail of the result. It is useful for a quick sanity check, but far too small to judge layout or typography — that is what the preview link is for.

Tools

ToolWhat it doesCredits
create_preview_linkBuild a live, shareable preview URL for a draft0
generate_image_from_htmlRender HTML into a PNG1
generate_image_from_templateRender a saved template into a PNG1
generate_images_from_templateRender up to 50 PNGs from one template in one call1 per image
generate_pdf_from_htmlRender HTML into a PDF (up to 100 pages)1 per 20 pages
generate_pdf_from_templateRender templates into one PDF (up to 100 pages)1 per 20 pages
check_pdfCount the pages of final HTML and list warnings0
create_templateSave HTML as a reusable template0
update_templateRename a template, or replace its HTML under its ID0
delete_templateDelete a template for good (local server only)0
list_templatesList the templates on your account0
get_templateFetch one template’s HTML and variable defaults0
list_rendersList your images or PDFs with their links0
get_creditsShow the credits left and when they expire0
ParameterTypeDescription
htmlstringRequired. HTML/Handlebars to preview. Not base64-encoded.
variablesobjectValues to fill the placeholders for this preview.
viewportWidthintegerWidth in pixels (default 1280).
viewportHeightintegerHeight in pixels (default 800).

generate_image_from_html

ParameterTypeDescription
htmlstringRequired. HTML with inline CSS. Not base64-encoded.
viewportWidthintegerWidth in pixels (default 1280).
viewportHeightintegerHeight in pixels (default 800).
transparentBackgroundbooleanRender on transparency instead of white.
inspectbooleanAlso return a 512px thumbnail of the result.

Returns the image id and its public URL. Mirrors Create Image from HTML.

generate_image_from_template

ParameterTypeDescription
templateIdstringRequired. Id of an existing template.
modifyobjectPer-render values, merged over the template’s variable defaults.
viewportWidthintegerWidth in pixels (default 1280).
viewportHeightintegerHeight in pixels (default 800).
transparentBackgroundbooleanRender on transparency instead of white.
inspectbooleanAlso return a 512px thumbnail of the result.

Mirrors Create Image from Template.

generate_images_from_template

ParameterTypeDescription
templateIdstringRequired. Id of an existing template.
modificationsarrayRequired. 1 to 50 objects, one per image, each a Modify Payload.
viewportWidthintegerWidth in pixels (default 1280).
viewportHeightintegerHeight in pixels (default 800).
transparentBackgroundbooleanRender on transparency instead of white.
strictbooleanRefuse the whole call, before any render, when an image would have warnings.

Returns each image’s URL in input order, then a failed: line for each image that did not render. 1 credit per image. Mirrors Create Bulk Images.

generate_pdf_from_html

ParameterTypeDescription
htmlstringRequired. HTML with inline CSS. Not base64-encoded.

Returns the PDF id, its public URL, the page count and the credits spent, 1 per 20 pages rounded up. Pages are A4 unless a CSS @page rule sets the size and margins. A PDF longer than 100 pages is refused and costs nothing. Mirrors Create PDF from HTML.

generate_pdf_from_template

ParameterTypeDescription
templateIdstringId of an existing template. With pages, the default template.
modifyobjectPer-render values, merged over the template’s variable defaults.
pagesarrayUp to 100 entries of { templateId?, html?, modify? }, merged in order into one PDF.

Returns the PDF id, its public URL, the page count, the credits spent and, with pages, the pages each entry printed. Page size is a CSS @page rule first, then the template’s saved size, then A4. Mirrors Create PDF from Template.

check_pdf

ParameterTypeDescription
htmlstringRequired. Final HTML, with sample values in place of {{ }}.

Returns the page count and the render warnings, and stores nothing. Use it to check page breaks before a paid render. No credit, up to 30 checks an hour.

create_template

ParameterTypeDescription
htmlstringRequired. HTML/Handlebars with {{variable}} placeholders.
variablesobjectDefault values for the placeholders — the template’s shape.
namestringA name you will recognise, 1 to 120 characters.
descriptionstringUp to 300 characters.
viewportWidthintegerWidth of the template’s preview and PDF renders.
viewportHeightintegerHeight of the template’s preview and PDF renders.

Image renders do not read the saved size, so pass the viewport on every image render too. Mirrors Create Template.

update_template

ParameterTypeDescription
templateIdstringRequired. Id of a template on your account.
namestringA new name. Given alone, it renames without touching the design.
htmlstringThe new HTML/Handlebars.
variablesobjectNew default values. Left out, the stored defaults stay.
viewportWidth, viewportHeightintegerA new size, kept only together with html or variables.

Give at least one of name, html or variables. The template keeps its ID, so API renders and the oJo editor open on it use the new version at once. Check the design with create_preview_link first. Your AI client may ask you to confirm the call, because it overwrites. No credit. The editor’s “Use with your AI” gives your AI a prompt that ends with this call.

delete_template

ParameterTypeDescription
templateIdstringRequired. Id of a template on your account.

The template and its ID stop working for every later render, and you cannot undo it. Your AI client may ask you to confirm the call. Mirrors Delete Template.

Only the local server has this tool. An AI app connected to mcp.ojo.so can render and read but not delete, so delete a template from the dashboard  there.

list_templates

ParameterTypeDescription
pageinteger1-based page number (default 1).
pageSizeintegerTemplates per page (default 10).
sortenumasc or desc by creation time (default desc).

get_template

ParameterTypeDescription
templateIdstringRequired. Id of the template to fetch.

Returns the template’s HTML — you can pass it straight to create_preview_link to preview a set of modify values before spending a credit on them.

list_renders

ParameterTypeDescription
formatenumRequired. image or pdf.
pageinteger1-based page number (default 1).
pageSizeintegerRenders per page, 1 to 100 (default 10).
sortenumasc or desc by creation time (default desc).

Returns each render’s ID, link and creation time, and a PDF’s page count. Deleted renders are not listed. Mirrors List Images and List PDFs.

On the remote server the list has no links. Anyone with a file’s link can open it, so an AI app misled by text in a page it read cannot collect them all. Open a file from Renders  on the dashboard.

get_credits

No parameters. Returns the credits left, the credits your current batches held, and when the last of them expires. Mirrors Get Credits.

Prompts

Prompts are ready instructions your AI client can load, often from a / menu.

  • author_ojo_template teaches the template rules: placeholders, the helper list, Template Variables and the Modify Payload, and the preview loop.
  • template_from_document turns a PDF or image you already have, such as an invoice or a design export, into a saved template. See Template from a PDF or image.

Variables

Two different things share the word “variables”, and the tools keep them apart:

  • Template Variables — the defaults you pass to create_template. They describe the template’s shape: which placeholders exist and what they hold when nothing overrides them.
  • Modify Payload — the per-render values you pass as modify to generate_image_from_template (or as variables to create_preview_link). They are merged over the defaults for that one render and change nothing on the template.

Templates are rendered with Handlebars, so conditionals, loops and helpers all work — see Template Helpers for the full list. Two things catch people out: {{value}} escapes HTML, so use {{{value}}} when a variable contains markup, and formatDate renders in local time rather than UTC.

Disconnect

Each connected app appears as an “MCP · ‹app name›” key under API keys . Delete the key and the app stops working within a minute. An account can have up to 20 connected apps.

Caveats

Local server: restart the client after upgrading. npx -y caches the package rather than re-resolving it on every run, and a running MCP server keeps whatever version it started with. If a newly released tool doesn’t appear, find the cached copy:

find ~/.npm/_npx -maxdepth 5 -type d -path '*@ojodotso/mcp-server'

Delete the _npx/<hash> directory that contains it — not all of ~/.npm/_npx, which caches every other tool you run through npx — then restart your MCP client so it spawns a fresh server.

Errors are returned as readable text, not raised as protocol errors, so the agent can act on them: a missing or invalid key reports Unauthorized (on the remote server: reconnect oJo in your AI app), an exhausted balance reports the API’s message with the pricing link, and hitting a rate limit reports Rate limited by the oJo API.

Preview links are self-contained and unverified. Everything in a /preview#draft= link lives in the URL fragment, which is why nothing is stored and no credit is charged — but it also means the content is supplied entirely by whoever built the link, not by oJo. The draft is rendered inside a sandboxed iframe that cannot reach your oJo session, so opening one is safe in that sense. Still, treat a preview link you received from someone else the way you’d treat any untrusted web page: it can run its own scripts, and the page it shows is theirs, not ours.