The Bitgrain connector lets an assistant such as Claude or ChatGPT operate Bitgrain for you: develop a photo in the darkroom, open a template, edit its layers and render real files. It is a tool your assistant uses. Nothing is generated, every pixel comes from the same deterministic engine the web app runs.
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.
| Area | What it does | Tools |
|---|---|---|
| Darkroom | One 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_list_palettes, darkroom_list_films, darkroom_render |
| Text output | ASCII, Braille and grunge ASCII returned as real characters, or as an SVG with one glyph per cell | darkroom_export_text |
| Templates | Browse the template library and open one as an editable document | list_templates, open_template |
| Documents | Create, open, describe, list, save and close layered multi-page documents | create_document, open_document, save_document, describe_document, list_documents, close_document |
| Layers | Add, update, remove, reorder, duplicate and inspect layers, one at a time or in batches | add_layer, add_layers, update_layer, update_layers, remove_layer, reorder_layer, duplicate_layer, inspect_layer |
| Effects | Stack Bitgrain effects on a layer | list_effects, list_presets, apply_effect |
| Render | Render one page, every page, or a single image with effects | render_page, render_all_pages, apply_effect_to_image |
| Outputs | List finished files, show one in the chat, get a fresh download link, read text output | list_outputs, show_image, get_download_url, read_text_output |
| Design skills | Short design briefs the assistant can read before it starts | list_design_skills, load_design_skill |
| Account | Sign in, sign out, check your plan, start the trial | bitgrain_login, bitgrain_logout, bitgrain_account, bitgrain_start_trial |
You do not need to know these names. Ask in plain language, for example "make this photo look risograph printed in two inks" or "turn this into ASCII I can paste into a README", and the assistant picks the tools.
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:
| Skill | For |
|---|---|
layout-grid | Margins, spacing and type scale. The others build on it. |
poster | Gig posters, flyers, anything read from a distance |
album-cover | Square art that still reads as a small thumbnail |
social-post | Feed and story sizes, safe areas, one message |
print-piece | Zines, riso looks, newsprint, deliberate imperfection |
photo-treatment | Choosing between halftone, dither, ASCII, grade and texture |
In clients that show MCP prompts, the same briefs appear as prompts named like design-poster.
Animation, video, riso separation files and mockups are not available through the connector. Use the web app for those.
There are three ways in. Which one you use depends on your client, not on a setting you choose.
Claude and ChatGPT connect from their own servers, so they use the connector address directly and sign you in with a standard authorization flow.
https://api.bitgrain.app/mcp as its URL.Other MCP clients that support remote servers with sign-in, such as Claude Code and Cursor, can use the same address.
Some clients cannot run the full sign-in flow. For those, the assistant signs you in with a code instead:
XXXX-XXXX.The code works once and expires after ten minutes. If the page says "that code is not recognised" or "this code is no longer good", ask the assistant to start again for a fresh one.
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. The /mcp page shows the command for Claude Code.
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 account | Needs Pro or the trial |
|---|---|
| Listing presets, modes, palettes and film grades | darkroom_render |
| Browsing and opening templates | darkroom_export_text |
| Reading design skills | render_page |
| Creating, editing and saving documents and layers | render_all_pages |
| Listing and applying effects to layers | apply_effect_to_image |
| Listing outputs and getting download links | |
| Account tools |
When a render is refused because the account is on the free plan, that is expected, not a broken connector. The assistant is told to explain that rendering needs a plan and to give you two options in the same reply:
bitgrain_start_trial, and Pro switches on straight away for the connector and the web app alike.Once you are on Pro or the trial, ask the assistant to try the render again. More on both in plans and pricing.
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.
Every render comes back with:
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.
A document the assistant saves with save_document is a Bitgrain project file. Ask for its download link and you can open it in the studio and keep editing by hand.
See privacy and determinism for how the rest of Bitgrain handles your data.
Every connected assistant appears on your account page under Connected assistants, with the date it was connected and when it was last used.
| What you see | What to do |
|---|---|
| The assistant says it needs to sign in | That is normal before the first real tool call. Follow the link and approve it. |
| A render is refused with a message about a plan | Your account is on the free plan. Start the trial or buy the licence, then ask again. |
| The assistant cannot read an image | Give it a public https link instead of an attached file. |
| A download link does not open | Links expire after twelve hours. Ask for a fresh one. Files older than fourteen days are gone. |
The code at /connect is refused | It was used, turned down or timed out. Ask the assistant for a new one. |