MCP Guide

Status: live. The API endpoints behind every tool are live.

The Yapper hosted MCP connector is a thin client over the public API. It contains no provider logic, Firebase reads, credit accounting, model routing, or private serializers.

Install

Hosted connector (recommended):

https://yapper.so/mcp/connector

Paste that URL into an MCP client that supports hosted HTTP connectors, then sign in with your Yapper account when prompted.

The hosted connector supports local files through a signed-upload handshake. A remote server cannot open a path on your computer itself, so the MCP client does the byte transfer locally:

1. Call yapper_create_asset_upload with the file's MIME type and optional name.
2. PUT the raw file bytes to the returned uploadUrl, including every returned header exactly.
3. Call yapper_complete_asset_upload with the returned assetId.

The completed asset's hosted URL can then be passed to a generation. Local stdio clients can use yapper_upload_asset instead; it performs all three steps in one call. Use yapper_import_asset only for media that already has a public HTTP(S) URL. Agents should never send users to the Yapper UI just to upload a local file.

In ChatGPT, attach the file to your message instead. yapper_import_file declares an Apps SDK file parameter, so ChatGPT hands Yapper a temporary download link for the attachment and Yapper stores it as an asset. Google Drive links work with yapper_import_asset when the file is shared as "Anyone with the link".

Grouping work into sessions

Sessions are the workspaces that group generations in the Yapper web app. To keep a project's work together, create one with yapper_create_session (or pick one with yapper_list_sessions) and pass its sessionId to yapper_start_process, yapper_import_asset, and uploads. The process and its outputs then appear together in that session. yapper_update_session renames a session or sets its image from an asset, and the session's webUrl opens it in the web app. Without a sessionId, outputs only appear in the team's asset library.

To pick up where the in-app Yapper agent left off, yapper_list_session_messages reads the session's conversation, newest first: each message's text, the asset ids of its attachments, and the steps the agent took. The agent's reasoning and its tool data are not included.

Working inside a session's workspace

Each session has a workspace: the folders, media, text documents, notes, and pins you see in the web app, which the in-app Yapper agent also works from. Start with yapper_get_workspace to see the tree. Items are addressed by id or by path, such as /Characters/hero, and yapper_read_workspace_item reads a folder's contents, a document's text, or an asset. yapper_create_workspace_folder, yapper_write_workspace_document, and yapper_place_assets_in_workspace create folders, write text documents, and file existing media into a folder. yapper_update_workspace_item moves, renames, pins, or annotates an item, and yapper_remove_workspace_item takes it out of the tree without deleting any assets. Removing a tree item does not always take its media out of the session, so the result lists what left and what is still there unfiled; yapper_remove_assets_from_session takes media out of the session itself, filed or not. Pass workspaceFolderId to yapper_start_process to file its outputs into a folder as they finish.

Everything you change shows up in the web app, and the in-app Yapper agent in that session is told about it on its next turn. For multi-step productions, write a brief (for example /Brief.md with brief: true): the in-app agent always reads it.

Building on a session's canvas

Each session also has a node canvas, the Canvas tool in the web app: text, image, video, and audio cards wired into image, video, and LLM generation cards. yapper_get_canvas returns every card with its settings, ports, and latest versions, plus the wires between cards. yapper_add_canvas_nodes adds up to 50 cards in one call, already wired: give a card a ref and later cards wire from it with inputs: [{ sourceRef }]. Media cards take an asset id and join the session; generation cards take a model from yapper_list_models (or, for LLM cards, from textModels in yapper_get_canvas) and that model's settings. yapper_update_canvas_node, yapper_connect_canvas_nodes, yapper_disconnect_canvas_nodes, and yapper_remove_canvas_nodes edit the graph; wires are checked like a drag in the app. yapper_update_canvas_nodes edits up to 100 cards in one call (all or nothing), for example to lay cards out in a grid. While a client edits, the canvas shows it in the header and its cursor on the card it last touched, like another member.

yapper_run_canvas runs generation cards in wiring order, each one reading the selected output of the cards that feed it. It spends credits, so quote it first with dryRun: true, and pass an idempotencyKey on the real run. The run continues on the server with no tab open; poll yapper_get_canvas_run for each card's state and outputs, and yapper_cancel_canvas_run takes cards that have not started out of the queue. Every change shows up live on the canvas in the web app.

Client integration rules

• Use the exact HTTPS connector URL above. Do not rewrite it to http://.
• A 401 response from /mcp/connector before sign-in is expected. It includes WWW-Authenticate metadata that points the MCP client to the OAuth protected resource metadata.
• Do not configure /api/mcp/oauth/* as the MCP server URL. Those routes are only the OAuth registration, authorization, approval, and token endpoints.
• Do not treat an unauthenticated JSON-RPC call as a connector failure. Complete the hosted MCP OAuth flow first, then call initialize and tools/list.

Tools

Resources

yapper://processes/{processId}
yapper://assets/{assetId}

Use resources/templates/list to discover these templates and resources/read to fetch one process or asset as JSON.

Agent behavior

• Call yapper_get_credits before expensive work when the user asks about feasibility.
• Call yapper_whoami before mixing hosted and local connectors.
• Quote paid work with yapper_estimate_process, tell the user what will be generated and the total credits, and wait for their go-ahead before the first paid run of a batch. Skip the wait only when they already approved that exact batch or gave a credit budget that covers it.
• Use idempotency keys for retried yapper_start_process calls.
• Poll process status instead of assuming immediate completion, waiting the returned suggestedPollAfterSeconds before each yapper_get_process call.
• Return asset ids and URLs from the public response shape only.

Security boundary

The hosted MCP connector uses 24-hour ymcp_ access tokens plus rotating 90-day refresh tokens from the Yapper OAuth flow. Active clients renew the refresh window automatically. Local stdio MCP clients receive credentials from local config or environment. MCP clients should never request browser session cookies or Firebase credentials.