Yapper Docs

MCP Guide

The Yapper hosted MCP connector — a thin client over the public API.

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.

Elements: characters, locations and props

Elements are the workspace's named references: a character, location or prop with an @ID that prompts tag (@hero), a main image, and other images. They belong to the whole workspace (every member but guests sees and edits them), and adding an image to one shares it with everyone through the element.

  • yapper_list_elements lists them newest first. Filter by category or by a session they were made or used in, or search with query: the start of an @ID, name or image name is enough (sam-al finds @sam-alman).
  • yapper_get_element reads one by id or @ID.
  • yapper_create_element makes one from image assets. mentionId is its @ID and its name, and must be free in the workspace (a clash answers with a free one to use, like @hero-2).
  • yapper_update_element renames the @ID, sets the category or description, adds or removes images, picks the main image, and names images.
  • yapper_delete_element deletes one for the whole workspace. Its images stay.

Naming an image (imageNames) lets a prompt use that image alone: @hero:coat-on is the element's image named coat-on, while plain @hero is its main image. New character sheets are named sheet-1, sheet-2 and so on.

To use elements in a generation, pass them in input.elements on yapper_start_process (ids or @IDs, @hero:coat-on included) and tag each in the prompt the same way:

{
  "type": "video-generation",
  "model": "kling-4.0",
  "input": {
    "prompt": "@hero:coat-on walks into @tavern",
    "elements": ["@hero:coat-on", "@tavern"]
  }
}

Video models whose capabilities list maxReferenceElements take elements natively. Image models, and other video models that take reference images, get each element's image as a reference named by its tag, counted against maxReferenceImages. The tags bind to those images; an element's name and description are never sent to the model. A tag in the prompt alone attaches nothing, and an unknown element or image name fails the request before it starts.

Each element has a webUrl that opens it in the web app (each named image has one that opens the element on that image). For the element library itself, call yapper_get_app_link with view: "elements".

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.

Cutting a session's timeline

Each session also has a video timeline, the Timeline tool in the web app. yapper_get_timeline returns its clips (each with its asset, track, timing, trim, volume, framing, and effects), transitions, text and captions, and a webUrl that opens it fullscreen. yapper_edit_timeline applies a list of operations in order with the editor's own rules: add team assets as video, image, or audio clips, then move, trim, reframe, remove, add transitions, set a clip's look or keyframes, and add or style text. It makes the timeline if the session has none, and saves all or nothing. Give a new clip a ref to use it later in the same call, and pass an idempotencyKey: a retry with the same key and operations returns the first result instead of editing again. yapper_caption_timeline transcribes the audio into timed captions. Edits show up live in an open timeline. Nothing renders through MCP: share the webUrl so the user can play and export the video in the app.

Editing in the Editor

The Editor is the session's image and video editing tool. yapper_get_editor lists the assets in its strip and its running edits; yapper_add_to_editor and yapper_remove_from_editor change the strip. To edit, call yapper_start_process with the sessionId and editor: true: an image or video generation with the asset as a reference, an upscale, or background-removal (a transparent PNG). The outputs join the strip as they finish, like the editor's own buttons.

yapper_get_app_link returns a link to hand the user: the session, its timeline or canvas fullscreen, or the Editor open on one asset (assetId), optionally on a panel (editorTab). Without a sessionId it links pages outside any session: view: "elements" for the element library (with element, an id or @ID like @hero or @hero:coat-on, that element opens on that image) and view: "library" for the asset library.

Inviting people and sharing projects

Use yapper_invite_to_project with a session ID, an email, and a project role. An existing workspace member gets the project role directly. Someone new gets an email invitation as a project-only guest by default. Only workspace owners and admins can invite guest editors.

Use yapper_invite_to_workspace to invite someone to the workspace itself. Owners and admins can invite members. Only owners can invite admins. New invitations require an available seat.

Use yapper_get_project_access to inspect access and yapper_update_project_access to change member roles, workspace-wide access, or project ownership. Removing an explicit role can leave access through a workspace role or the project's general access setting.

Before a sharing write, confirm the workspace, project if applicable, recipient, and role or access change with the user. Sharing writes require sharing:write and appear in the audit log as public-api. Existing hosted connections can approve Sharing on first use. For local stdio, enable Sharing on the API key.

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

ToolPurposeStatus
yapper_load_skillLoad image or video prompting guidanceLive
yapper_whoamiShow connected team, your role, and scopesLive
yapper_estimate_processQuote a generation's credits without starting itLive
yapper_start_processStart a generation process (spends credits)Live
yapper_generate_speechLegacy synchronous speech (may spend credits)Live
yapper_get_processPoll one processLive
yapper_list_processesList recent processesLive
yapper_list_assetsList generated or imported assetsLive
yapper_get_assetFetch one assetLive
yapper_show_assetsShow assets in a numbered grid (widget hosts)Live
yapper_update_assetFavorite an asset, or restore it from the trashLive
yapper_trash_assetMove an asset to the trash (purged after 60 days)Live
yapper_import_assetImport an external HTTP(S) assetLive
yapper_import_fileImport a file attached in ChatGPTLive
yapper_create_asset_uploadCreate a hosted signed-upload ticketLive
yapper_complete_asset_uploadFinalize a hosted signed uploadLive
yapper_upload_assetUpload a local path in one call (local stdio only)Live
yapper_list_modelsList available models and capabilitiesLive
yapper_get_model_schemaFetch one model's authenticated input schemaLive
yapper_list_audio_voicesList voices compatible with an audio modelLive
yapper_list_sessionsList or search the team's sessionsLive
yapper_get_sessionRead one session and its web linkLive
yapper_list_session_messagesRead a session's chat with the in-app Yapper agentLive
yapper_create_sessionCreate a session to group workLive
yapper_update_sessionRename a session or set its imageLive
yapper_add_assets_to_sessionAdd existing assets to a sessionLive
yapper_remove_assets_from_sessionTake media out of a session (keeps the assets)Live
yapper_get_workspaceList a session's folders, files, and unfiled mediaLive
yapper_read_workspace_itemRead a folder, a document's text, or an assetLive
yapper_create_workspace_folderCreate folders along a workspace pathLive
yapper_write_workspace_documentCreate or overwrite a text document or the briefLive
yapper_place_assets_in_workspaceFile existing media into a workspace folderLive
yapper_update_workspace_itemMove, rename, pin, or annotate a workspace itemLive
yapper_remove_workspace_itemRemove an item from the tree (keeps its assets)Live
yapper_get_canvasRead a session's canvas: cards, wires, versionsLive
yapper_get_canvas_nodeRead one canvas card with every versionLive
yapper_add_canvas_nodesAdd wired cards to a canvasLive
yapper_update_canvas_nodeEdit a card's prompt, model, settings, or layoutLive
yapper_update_canvas_nodesEdit up to 100 cards at once (e.g. a re-layout)Live
yapper_remove_canvas_nodesRemove cards and their wiresLive
yapper_connect_canvas_nodesWire one card's output into another cardLive
yapper_disconnect_canvas_nodesRemove a wire between two cardsLive
yapper_run_canvasRun canvas cards in order (spends credits)Live
yapper_get_canvas_runCheck a canvas run's progress and outputsLive
yapper_cancel_canvas_runTake queued cards out of a canvas runLive
yapper_get_timelineRead a session's timeline and its fullscreen linkLive
yapper_edit_timelineAdd, trim, and style clips, text, and transitionsLive
yapper_caption_timelineCaption a timeline's audioLive
yapper_get_editorRead the Editor strip and its running editsLive
yapper_add_to_editorPut images or videos in the EditorLive
yapper_remove_from_editorTake items out of the Editor (keeps the assets)Live
yapper_get_app_linkLink to a session or tool, elements, or libraryLive
yapper_get_project_accessRead project access settingsLive
yapper_update_project_accessChange project access or ownershipLive
yapper_invite_to_projectInvite someone to a project by emailLive
yapper_invite_to_workspaceInvite someone to the connected workspaceLive
yapper_get_creditsCheck team credit balanceLive
yapper_get_usageTeam credits, member and API key credit limitsLive
yapper_get_usage_breakdownCredit spend by model and source over timeLive
yapper_get_usage_cycleThis billing cycle's credits and the next refillLive
yapper_get_agent_usageIncluded agent allowance and usage by modelLive
yapper_list_usage_ledgerList individual credit charges and refundsLive
yapper_list_session_usageList sessions with their all-time spendLive
yapper_list_member_usageSpend per member (owner or admin connection)Live
yapper_list_membersTeam members with their rolesLive
yapper_get_storage_usageStored bytes and asset counts by typeLive
yapper_show_credit_usageShow the credit balance and refill (widget hosts)Live
yapper_show_creditsShow credits and packs to buy (widget hosts)Live
yapper_buy_creditsBuy a confirmed pack (credits widget only)Live
yapper_list_elementsList or search the workspace's elementsLive
yapper_get_elementRead one element by id or @IDLive
yapper_create_elementMake an element from image assetsLive
yapper_update_elementRename, describe, or change an element's imagesLive
yapper_delete_elementDelete an element (keeps its images)Live

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.
  • Give the user the links the API returns (webUrl, or yapper_get_app_link for a page like the element library) instead of building URLs.

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.

On this page