Choose How Users Reach the Agent

This guide covers what you build and run for each way, and how to choose.

Two Ways In#

Every way uses the same call: prepareCoDesign from @imgly/codesign-sdk returns the design tools, functions a model may call to edit a design, look at a preview of it, or export it. You call it once for each conversation, the unit of work the tools serve: one chat, one job, or one MCP session. The ways differ in who runs the agent loop, the loop that sends the model the task and the tools, runs each tool the model asks for, and sends back the result.

• Your own agent loop in your product. Your code calls the model and hands it the tools. The chat, or the API request, is yours: a design chat next to a person’s designs, or a service that turns a brief into finished files.
• A remote MCP server. Your users add your server’s address to their own AI assistant (Claude, ChatGPT, Cursor, or an agent they built). The assistant runs the loop and its model calls your tools.

In both, the design engine runs in an executor, a container from IMG.LY’s published Docker image that runs on your infrastructure and applies the model’s edits. Your designs stay in your store. Exports and AI use are charged to your IMG.LY account, as described in Billing.

Your Own Agent Loop in Your Product#

Your agent runner, the server process that runs the loop, calls prepareCoDesign for each request, hands the model codesign.tools, and ends your system prompt with codesign.instructions, a few sentences the SDK supplies. The SDK calls no model itself: you can use IMG.LY’s AI gateway, which charges the same credits as exports, or any provider whose models can call tools. With gateway: { bearer }, the agent can also generate images. Two shapes are common:

• A design chat. A person types a brief next to their designs and watches the design appear, then asks for changes in the next message. The runner runs one turn per message as a job and streams progress. See Add a Design Chat to Your Product.
• A design API. A request goes in, finished designs come out, with no chat: one job per requested format, such as a batch of resized posts. See Generate Designs From Your Backend.

Your product owns the whole experience: the prompt, the model and its cost, the chat window, approval before a change reaches a design, and a hand-off to your editor built on CE.SDK, IMG.LY’s design editor for the browser (see Your Editor).

A Remote MCP Server#

MCP is an open standard for giving an AI assistant tools. An MCP server lists its tools and runs them when the assistant, the MCP client, calls them. The SDK’s tools already have the shape MCP expects, so the server is a short mapping over them, written once with MCP’s own TypeScript SDK. See Serve the Design Tools as an MCP Server.

• The model is theirs. The assistant’s subscription pays for the model’s tokens. You pay for exports and generated images, not for model calls.
• The chat is theirs. You build no chat window. What people see is their assistant’s: the tool calls, the previews, the links you return.
• Your server builds the tools per MCP session, the connection an assistant opens to your server, from the caller’s credentials: one prepareCoDesign per session, with that customer’s design store (where your product keeps designs) and plugin modules (the JavaScript files that give the engine your brand and files).
• Sign-in is yours to check on every request. Hosted assistants sign in with OAuth 2.1, the standard flow for an app acting on a person’s behalf, and your sign-in plays the authorization server, the service that signs people in and issues their tokens.
• Your server cannot show the person a confirmation. Confirming a charge is the assistant’s approval of each tool call, or a check you add before a tool runs.

What Each Needs From You#

The middle rows are the same work in both: the design store, your plugin modules, and uploadExport, a function that hands finished files to your storage (see Connect Your Storage and Bring Your Brand), and the executor on your servers (see Host the Executor).

Which to Pick#

• Pick your own agent loop when the agent belongs inside your product: your prompt and model, a chat next to the design grid, an approval step, an editor for finishing touches, or an API your customers call with a brief.
• Pick a remote MCP server when your customers already work in an AI assistant and want your designs and brand there, and you want to run no model and build no chat.

Running Both#

The ways share everything below the tools, so you can offer both:

• One setup. Both call prepareCoDesign with the same design store, plugin modules, and uploadExport, built from the caller’s credentials. Only the last few lines differ: who calls the tools.
• One conversation, one executor. Every design a conversation works on opens in an executor no other conversation uses, because the model’s code runs there (see Security). Prefix the conversation id with your customer’s id, so two customers never share one.
• Designs outlive conversations. A design made in your chat opens from an assistant through the same store, and the other way around. If both save the same design, the stale save is refused and the model is told (see Concurrent Edits).

Next Steps#

• Add a Design Chat — build your own agent loop, step by step.
• Generate Designs — turn a brief into finished files.
• Serve the Design Tools as an MCP Server — give your users’ own assistants the tools.
• Connect Your Storage — build the design store every way shares.
• Host the Executor — run IMG.LY’s image, one container per conversation.