Connect AI assistants

The Bitgrain connector lets an assistant such as Claude or ChatGPT operate Bitgrain for you: develop a photo in the darkroom, pick and open a template, edit its layers and pages, animate it, render real files, and bundle them into a PDF, a PowerPoint deck or a video. Everything it builds is saved to your library, so you can open it in the studio and keep editing by hand. It is a tool your assistant uses. Nothing is generated, every pixel comes from the same deterministic engine the web app runs.

What the connector is

The connector is an MCP server. MCP (Model Context Protocol) is an open standard that lets an assistant call tools. Once connected, your assistant can see a list of Bitgrain functions, such as "render this photo with this preset" or "change the text on layer 3", and call them on your behalf.

The important part is what it is not. It is not an image generator with a chat window on top. The assistant only picks settings and calls functions, the way you would click controls. Those functions are the same halftone, dither, ASCII, riso-style and film grade code the web app ships, run on Bitgrain's server without a browser. Give it the same inputs next year and the same file comes out.

The connector address is:

https://api.bitgrain.app/mcp

The /mcp page has an overview with examples.

What your assistant can do

AreaWhat it doesTools
DarkroomOne photo in, one processed photo out, using a named preset or a chain of effects. Every parameter's key, range and default can be looked up first, so nothing is guessed.darkroom_list_presets, darkroom_list_modes, darkroom_render
Text outputASCII, Braille and grunge ASCII returned as real characters, or as an SVG with one glyph per celldarkroom_export_text
TemplatesSearch the template library, show you a few to pick from as a grid of previews, and open your pick as an editable documentlist_templates, show_template_choices, open_template
DocumentsCreate, open, describe, list, save and close layered multi-page documentscreate_document, open_document, save_document, describe_document, list_documents, close_document
PagesAdd, duplicate, remove and reorder pages, for example to fit a deck to your content, and write speaker notesadd_page, duplicate_page, remove_page, reorder_page, set_page_notes
LayersAdd, update, remove, reorder, duplicate and inspect layers, one at a time or in batchesadd_layers, update_layers, remove_layer, reorder_layer, duplicate_layer, inspect_layer
ComponentsList a document's reusable components and place instances of themlist_components, insert_instance
EffectsStack Bitgrain effects on a layerlist_effects, apply_effect
RenderRender one page or every pagerender_page, render_all_pages
AnimationAnimate a page with a preset or with keyframes per layer, then export it as MP4, GIF, Lottie or animated SVGset_page_animation, set_layer_track, set_layer_keyframes, clear_page_animation, export_animation
ExportCombine pages into one PDF, or a .pptx deck that opens in PowerPoint, Keynote and Google Slides. Each page keeps its real size, so A4 stays A4 and a 1920 by 1080 deck becomes a standard 16:9 slide.export_pdf, export_pptx
OutputsList finished files, show one in the chat, get a fresh download link, read text output, delete a filelist_outputs, show_image, get_download_url, read_text_output, delete_output
Design skillsShort design briefs the assistant can read before it startslist_design_skills, load_design_skill
AccountCheck your plan and renders left this month, sign out, and sign in on apps that use a device codebitgrain_account, bitgrain_logout, bitgrain_login

You do not need to know these names. Ask in plain language, for example "make this photo look risograph printed in two inks", "turn this into ASCII I can paste into a README" or "make me a five slide pitch deck and give me the PowerPoint", and the assistant picks the tools.

For posters, decks, resumes and other pieces with a familiar shape, the assistant is told to start from a template in the library and rewrite it for you, rather than build from a blank page, unless you ask for something no template fits. If you have not named a template or a look, it shows you a few templates first and waits for your pick.

Design skills

Tool descriptions say what a setting does, not what a good poster looks like. So the connector includes six short briefs the assistant can load before it builds something:

SkillFor
layout-gridMargins, spacing and type scale. The others build on it.
posterGig posters, flyers, anything read from a distance
album-coverSquare art that still reads as a small thumbnail
social-postFeed and story sizes, safe areas, one message
print-pieceZines, riso looks, newsprint, deliberate imperfection
photo-treatmentChoosing between halftone, dither, ASCII, grade and texture

In clients that show MCP prompts, the same briefs appear as prompts named like design-poster.

What it cannot do yet

The video editor, riso separation files and mockups are not available through the connector. Use the web app for those.

Connecting

There are three ways in. Which one you use depends on your client, not on a setting you choose.

A hosted connector (Claude, ChatGPT)

Claude and ChatGPT connect from their own servers, so they use the connector address directly and sign you in with a standard authorization flow.

  1. In your assistant's settings, add a custom connector and paste https://api.bitgrain.app/mcp as its URL.
  2. The assistant opens a Bitgrain page to sign you in. If you are not signed in to Bitgrain in that browser, sign in first.
  3. On the allow access screen, check the assistant's name and the email it will act as. The screen explains that it will be able to read your templates, run the darkroom and export images, and that you can disconnect it at any time from your account.
  4. Click allow (in some clients it reads allow and go back to followed by the assistant's name). Click not now if you change your mind.
  5. Go back to the assistant and ask for something.

Other MCP clients that support remote servers with sign-in, such as Claude Code and Cursor, can use the same address.

A short code

Some clients cannot run the full sign-in flow. For those, the assistant signs you in with a code instead:

  1. Ask the assistant to do something with Bitgrain. It will say it needs to sign in and give you a link and an eight character code, which looks like XXXX-XXXX.
  2. Open the link, or go to /connect and type the code into the Connection code box.
  3. Sign in to Bitgrain if asked.
  4. Check that the code on the allow access screen matches the one your assistant showed you, then click allow.
  5. The page says "You're connected". Head back to your assistant and carry on.

The code works once and expires after ten minutes. If the page says "We don't recognise that code", "This code has expired" or "This code was already used", ask the assistant to start again for a fresh one.

Private, on one machine

Developers can also run the connector locally over standard input and output, so nothing is hosted and the sign-in credential is a file on that one machine. For Claude Code, the quicker route is the hosted address: claude mcp add --transport http bitgrain https://api.bitgrain.app/mcp, which the /mcp page also shows.

Free tools and Pro tools

Every tool needs you to be signed in. After that, the split follows the web app: browsing and building are free, rendering finished files is Pro.

Free with any accountNeeds Pro
Listing presets, modes, palettes and film gradesdarkroom_render
Browsing, picking and opening templatesdarkroom_export_text
Reading design skillsrender_page
Creating, editing and saving documents, pages and layersrender_all_pages
Listing and applying effects to layersexport_pdf
Setting up animationexport_pptx
Listing outputs and getting download linksexport_animation
Account toolsSaving to your library

When a render is refused because the account is on the free plan, that is expected, not a broken connector. The connector answers with plan_required and a link to the pricing page, and the assistant is told to explain that rendering needs Pro and share that link. There you can pick the monthly plan, the yearly plan or the one-time 10-year license.

Once you are on Pro, ask the assistant to try the render again. More in plans and pricing.

Monthly renders

Pro includes 300 renders a month through the connector. A render is any tool call that produces a file: render_page, render_all_pages, export_pdf, export_pptx, export_animation, darkroom_render and darkroom_export_text. Each call counts once, so render_all_pages on a ten page deck is one render. Building, editing and browsing never count.

When you run out, the assistant gets a short message saying this month's renders are used up, the date they come back, and a link to your account page where you can add a pack. Nothing you built is lost. Once a pack is added or the month turns over, ask it to render again.

Giving it images

The connector runs on Bitgrain's server, not on your computer, so it cannot read a file you attached to the chat by its path. Give the assistant a public https link to the image, or a data URL. If you only have a local file, upload it somewhere that gives you a direct link first.

Getting your files

Every render and export comes back with:

A PowerPoint export also comes with a PDF preview link, because a browser cannot open a .pptx file directly.

Full-resolution files never go into the conversation itself, only a small preview and the links, so a large export does not flood the chat.

Links last twelve hours. If one has expired, ask the assistant for a fresh link to the same file. Rendered files are kept on the server for fourteen days and then deleted, so download anything you want to keep.

Your library

Every document the assistant opens or builds is saved to your Bitgrain library as a project, images included, and kept up to date as it edits. The assistant gets a studio link for it, so you can open the same project in the studio and keep editing by hand. Saving to the library needs Pro, like rendering.

save_document also writes a Bitgrain project file you can download.

Privacy

See privacy and determinism for how the rest of Bitgrain handles your data.

Managing and disconnecting

Every connected assistant appears on your account page under Connected assistants, with the date it was connected and when it was last used.

Troubleshooting

What you seeWhat to do
The assistant says it needs to sign inThat is normal before the first real tool call. Follow the link and approve it.
A render or export is refused with a message about a planYour account is on the free plan. Get Pro from the pricing page, then ask again.
A render is refused because this month's renders are used upWait for the reset on the 1st (UTC), or add a 250 render pack from your account page.
The assistant cannot read an imageGive it a public https link instead of an attached file.
A download link does not openLinks expire after twelve hours. Ask for a fresh one. Files older than fourteen days are gone.
The code at /connect is refusedIt was used, turned down or timed out. Ask the assistant for a new one.

More documentation