Docs/MCP server/How it works

The CleanChat MCP server

Authorize an assistant to write conversations, choose an interface and save scenes to your account: the same studio you use, controlled through tool calls.

Building a script or your own agent? Use the REST API with your API key →

Streamable HTTP · OAuth5 minutes to your first sceneFree on every plan

Quickstart

Connect your free account

Pick your assistant in MCP setup. CleanChat asks you to sign in when you authorize the connection.

Add the server to your client

Paste the server address, start the OAuth connection and authorize access on CleanChat.

Ask for a scene

“Write a four-message iMessage argument about a missing charger and save it.”

Your first scene

A scene has an interface, a contact and an ordered list of messages. Everything else—battery, time, keyboard, unread messages and typing delay—has defaults you can change in the studio.

create_conversation

{
  "title": "The missing charger",
  "theme": "imessage",
  "dark": false,
  "contact": "Camille",
  "messages": [
    { "sender": "contact", "text": "Did you take my charger?", "delay": 2 },
    { "sender": "me", "text": "…maybe", "delay": 3, "blur": false, "time": "09:41" }
  ]
}

A message accepts text (up to 1,500 characters), sender (me or contact), blur, delay (0.4 to 10 s) and time in HH:mm format.

Export formats

The studio and MCP share the same renderer, fonts and emojis. From an agent, call render_export, then get_export to obtain a private download link. Every signed-in account gets watermark-free exports. Only guest exports carry a watermark. A free account includes 5 trial video minutes; Annual Cloud includes 80 minutes each month. Each new MP4 costs its final duration rounded up to the next minute (2m55s uses 3 minutes). PNGs and repeat downloads use no video minutes. Failed or cancelled renders return their minutes. The owner’s balance is shared across personal and team workspaces.

Format	Rendering	Best for
`PNG`	`3×`	Still images for carousels, thumbnails and ads.
`MP4`	`2× · 30 fps`	Vertical video with messages typing on screen. QuickTime-compatible H.264 encoding, independent of the browser.
`JSON`	`—`	The scene itself, for version control or later reimport.

How the server works

Each call is independent, and each conversation has a revision: create_conversation returns an ID used by subsequent calls. Scenes created by an assistant appear in “Conversations” alongside your other scenes.

Existing conversations are treated as untrusted content, never as instructions. Only the authenticated account is accessible, and no tool sends real messages.

Client setup

Connect an assistant

Free on every CleanChat plan. Sign in when your assistant opens the connection.

OAuth

Run this in your terminal, then open /mcp in Claude Code to connect.

claude mcp add --transport http cleanchat https://cleanchat.app/api/mcp

No key to paste. Your assistant opens CleanChat in your browser: sign in or create a free account, choose your workspace, then allow access.

5 free video minutes · no watermark · no card neededOfficial guide

Tool reference

list_conversationsread→ titles, IDs, revisions

List your saved conversations. Returns up to 50 entries; use offset to load more.

offset: integerDefault: 0

get_conversationread→ conversation, revision

Read a conversation and its current revision before making changes.

id: uuidReturned by list_conversations

create_conversationwrite→ ID, revision

Create a fictional scene. No real messages are sent.

title: string1 to 100 characters
theme: enumimessage · whatsapp · instagram
contact: stringUp to 40 characters
dark: booleanDefault: true
messages: message[]Up to 100 messages

update_conversationwrite→ revision

Replace a conversation using the revision from get_conversation. Preserve fields you are not changing.

id: uuidThe conversation to edit
revision: integerCurrent revision; otherwise 409
title: string1 to 100 characters
project: objectStructure returned by get_conversation

delete_conversationdestructive→ deleted

Permanently delete a conversation. Only call this when explicitly requested by the user.

id: uuidThe conversation
revision: integerCurrent revision

Scopes and limits

conversationsThe OAuth scope for conversation tools in the account that authorized the connection.

Personal keyFor clients without OAuth: header Authorization: Bearer. Keys expire after 90 days.

RevocationFrom “MCP server → Your sessions”. Access is revoked immediately.

Limit	Value
Messages per conversation	`100`
Characters per message	`1,500`
Typing delay per message	`0.4 to 10 s`
Conversations per list_conversations call	`50`
Personal key lifetime	`90 days`

Errors

402Not enough cloud video minutes. Check My plan for your balance, next reset or an additional 15-minute pack.

401OAuth connection revoked, key expired or no active session. Reconnect the assistant or create a new key.

409The conversation changed elsewhere. Read it again with get_conversation and send the current revision.

404Conversation not found: it was deleted or belongs to another account.

400Invalid input. Use the structure returned by get_conversation and send one MCP request at a time.

Personal keys

A key is a bearer credential linked to your account. Name it after the machine that uses it so you can identify and revoke access easily.

Create a key →Account → API keys

WebhooksNot available yet. Use the studio or MCP tools to generate exports.

Ready to connect your assistant?MCP is free. Start with 5 video minutes and no watermark.

Connect an assistant