Reference

MCP server

Give an AI agent the ability to create, design, read, print and publish Composa documents. Your agent runs the conversation; Composa supplies the layers, the layout and the printing.

Endpoint


URL	`https://mcp.composa.dev/mcp`
Transport	Streamable HTTP
Sign-in	OAuth 2.1 in the browser — the agent finds it on its own. No API key.
Acts as	You, in the team you choose when you Allow

API keys do not connect the MCP; they are for the HTTP API. A client configured with one is asked to sign in instead — remove the Authorization header from its configuration and connect again.

Connect

Every agent needs only the URL above. The first time it connects, your browser opens: sign in to Composa, choose the team the agent may work in, and Allow.

Claude

Add to Claude — one click, then sign in as below.

Add as a custom connector

1.Open Claude's custom connector form — the button above, or this link:

Link

https://claude.ai/new?modal=add-custom-connector#customize/connectors/yours

2.Fill in the name and the server URL:

Name

Composa

Remote MCP server URL

https://mcp.composa.dev/mcp

3.Click Continue, leave the next screen as it is, and click Add.

4.On the next screen, click Connect: sign in to Composa, choose the team, and approve.

5.That's it — in Claude, ask it to make something with Composa.

Claude reaches Composa through its MCP server, as a custom connector. Added once, it works in Claude on the web and in the desktop app.

Claude Code

Add from your terminal

1.Open your terminal and run:

terminal

claude mcp add --transport http --scope user composa https://mcp.composa.dev/mcp

2.Start claude, type /mcp, choose composa and then Authenticate.

3.The first time it connects, your browser opens: sign in to Composa, choose the team, and Allow.

--scope user makes Composa available in every project. Without it, Claude Code only sees it in the folder you ran the command from.

Check and manage it

List every server Claude Code knows, see Composa's details, or remove it:

terminal

claude mcp list
claude mcp get composa
claude mcp remove composa

Codex

Add from your terminal

1.Add the server, then sign in:

terminal

codex mcp add composa --url https://mcp.composa.dev/mcp
codex mcp login composa

2.The first time it connects, your browser opens: sign in to Composa, choose the team, and Allow.

3.Start codex and run /mcp to see Composa's tools.

Or, add manually in ~/.codex/config.toml

config.toml

[mcp_servers.composa]
url = "https://mcp.composa.dev/mcp"

Then run codex mcp login composa.

Cursor

Install in Cursor — one click, then sign in as below.

Then sign in

In Settings → Tools & MCP, Composa shows Needs login: click Connect. The first time it connects, your browser opens: sign in to Composa, choose the team, and Allow.

Or, add manually in Cursor settings

1.Open Cursor → Settings → Cursor Settings → Tools & MCP

2.Under MCP Tools, click + to add a custom MCP server

3.Paste the code snippet into the mcp.json file and save

mcp.json

{
  "mcpServers": {
    "composa": {
      "url": "https://mcp.composa.dev/mcp"
    }
  }
}

VS Code

Add from your terminal

1.Add Composa to your VS Code user profile:

terminal

code --add-mcp '{"name":"composa","type":"http","url":"https://mcp.composa.dev/mcp"}'

2.Open Chat in Agent mode. When VS Code asks to sign in to Composa, Allow. The first time it connects, your browser opens: sign in to Composa, choose the team, and Allow.

Or, add manually in VS Code settings

1.Press Ctrl+Shift+P (⇧⌘P on a Mac) and run MCP: Open User Configuration

2.Paste the server into mcp.json and save

mcp.json

{
  "servers": {
    "composa": {
      "type": "http",
      "url": "https://mcp.composa.dev/mcp"
    }
  }
}

Other agents

Add manually in your agent's settings

1.Any agent that speaks MCP over Streamable HTTP and signs in with OAuth can connect. Check its documentation for where remote servers go.

2.It needs only the server URL — it finds the sign-in on its own:

URL

https://mcp.composa.dev/mcp

3.Most agents take it in this shape:

Code snippet

{
  "mcpServers": {
    "composa": {
      "url": "https://mcp.composa.dev/mcp"
    }
  }
}

4.The first time it connects, your browser opens: sign in to Composa, choose the team, and Allow.

Disconnecting

Press Room → Settings → Security lists every agent connected to your account. Disconnect takes effect on its next call, even if it still holds a token; connecting again asks you to Allow again.

What an agent can call. Your agent reads each tool’s own description when it connects; this is the same list for you. Operations (apply_ops) and the program API (compose) are documented to the agent itself, through get_ops_reference and get_guide.

Projects

Tool	What it does	Parameters
`list_projects`	Every project in the team the agent is connected to, newest first. A project never edited is marked not renderable.	none
`create_project`	A new project, in a page format, optionally started from a built-in template. Answers with its link in the editor.	title: string format?: a4 \| a5 \| letter \| legal \| square \| slide \| instagram-post \| instagram-story (default a4) template?: executive-report \| resume \| slide-deck \| invoice \| price-list \| letter \| newsletter \| certificate
`get_project`	The project as people see it now: page setup, theme, languages, pictures, variables and every layer with its id.	project_id: uuid query?: a selector such as TEXT[page=2], or "missing:es" depth?: "full" \| "pages"
`delete_project`	Moves a project to the bin. It is deleted for good after 30 days.	project_id: uuid

Designing

Tool	What it does	Parameters
`compose`	Writes a page as a short JavaScript program run in a sandbox; every builder makes a native, editable layer. All or nothing.	project_id: uuid code: string (up to 50 000 characters) preview?: true \| page number dry_run?: boolean
`apply_ops`	Edits a project with design operations. An invalid operation is skipped and reported by index; the rest apply.	project_id: uuid ops: object[] (1–200) reply?: "changes" \| "document" dry_run?: boolean
`brand`	The team's brand kit — faces, palette, text styles, reusable components and notes — read before designing, saved from a project.	action: "get" \| "save" \| "save_from_project" \| "list_components" project_id?: uuid theme? · textStyles? · components? · removeComponents? · notes? · logoAsset?
`finish_working`	Says the agent is done, so the people watching in the editor see it stop at once.	project_id: uuid

Pictures

Tool	What it does	Parameters
`create_image_upload`	A URL to PUT one picture to, valid for 5 minutes. PNG, JPEG, GIF, WebP or SVG, up to 2 MB.	project_id: uuid filename: string
`attach_image`	Adds the uploaded picture to the project under a name, and says its size in pixels.	project_id: uuid pending_id: string name: string (up to 60)
`list_images`	The pictures a project already has.	project_id: uuid

Printing

Tool	What it does	Parameters
`render`	Prints the current draft to PDF, PNG or SVG and returns a download link valid for one hour. Several items come back as one zip.	project_id: uuid format?: "pdf" \| "png" \| "svg" (default pdf) data?: object items?: { name?, data? }[] language?: string
`render_preview`	One page as a picture in the conversation, with a review checklist. `stress` fills every variable with long values to check they fit.	project_id: uuid page?: number (default 1) proof?: boolean (default true: half resolution) data?: object stress?: boolean language?: string record?: string
`publish`	Freezes the project as it is now into a new version — the one the HTTP API prints.	project_id: uuid note?: string accept_blank_languages?: string[]
`list_versions`	Every published version, newest first: which one the API prints, and whether the draft has changes not yet published.	project_id: uuid

Guidance

Tool	What it does	Parameters
`get_ops_reference`	The operations an agent can send: the short core with no argument, or the fields of the ones named.	op?: string ops?: string[] (up to 40)
`get_guide`	How to work: the skills (compose, design, data, brand, languages) and chapters such as composing a report or reviewing your work.	topic?: string

Resources

The skills get_guide serves are also MCP resources, for clients that load them up front: skill://composa/composa-compose/SKILL.md, and likewise composa-design, composa-data, composa-brand and composa-languages.

Draft and published version

A project has a draft— what is on screen right now, the agent’s edits and people’s alike — and the versionssomeone published. The MCP’s render prints the draft. The HTTP API prints only a published version, so an edit reaches your integration when someone runs publish (or presses Publish in the editor).

Pictures

Picture bytes never travel through the conversation. The agent asks for an upload URL, sends the file to it with an HTTP PUT, then attaches it under a name:

flow

create_image_upload { project_id, filename: "logo.png" }
  → an upload URL and a pending id

curl -X PUT "$upload_url" --data-binary @logo.png

attach_image { project_id, pending_id, name: "logo" }
  → the picture's id and its size in pixels

apply_ops { project_id, ops: [{ "op": "add_image", "assetId": "logo", "widthPct": 40 }] }

PNG, JPEG, GIF, WebP and SVG, up to 2 MB. The type is read from the file itself, not its name.
The upload URL works for 5 minutes; an upload that is never attached is never part of a document.
A picture belongs to the project: upload a logo once and use it by its name in any later edit. Uploading needs a way to make an HTTP request beside the MCP client (a shell); a chat-only client cannot add pictures.

Printing

render answers with a download link on this site, valid for one hour. Pass data to fill the variables, or items for several copies at once, returned as one zip — up to 100 per call. For larger runs, use the HTTP API from a script: it takes 500 per call.

render

{ "project_id": "…", "format": "pdf", "data": { "customer_name": "Alice Moreau" } }

{ "project_id": "…", "items": [
  { "name": "alice", "data": { "customer_name": "Alice Moreau" } },
  { "name": "bruno", "data": { "customer_name": "Bruno Lima" } }
] }

A document of several pages prints as one PDF; as PNG or SVG, each page is its own file, zipped. render_preview shows one page inside the conversation instead — what an agent uses to check its own work.

Working alongside people

Edits appear live in the editor for everyone with the project open, with the agent’s name on them.
If a person changed something the agent’s edit touches while it ran, the edit is applied again on the fresh document — nobody’s change is lost.
A text box someone is typing in is theirs: the agent waits up to 30 seconds, then answers with an error naming that person.

Errors

A tool that fails answers with a message for the agent (an MCP result marked as an error), not an HTTP error. In apply_ops, an invalid operation is skipped and reported by its index while the rest apply. “No such project” and “not in your team” are the same answer.