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/connectorPaste 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:
- Call
yapper_create_asset_uploadwith the file's MIME type and optional name. PUTthe raw file bytes to the returneduploadUrl, including every returned header exactly.- Call
yapper_complete_asset_uploadwith the returnedassetId.
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_elementslists them newest first. Filter bycategoryor by a session they were made or used in, or search withquery: the start of an @ID, name or image name is enough (sam-alfinds@sam-alman).yapper_get_elementreads one by id or @ID.yapper_create_elementmakes one from image assets.mentionIdis 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_elementrenames the @ID, sets the category or description, adds or removes images, picks the main image, and names images.yapper_delete_elementdeletes 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
401response from/mcp/connectorbefore sign-in is expected. It includesWWW-Authenticatemetadata 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
initializeandtools/list.
Tools
| Tool | Purpose | Status |
|---|---|---|
yapper_load_skill | Load image or video prompting guidance | Live |
yapper_whoami | Show connected team, your role, and scopes | Live |
yapper_estimate_process | Quote a generation's credits without starting it | Live |
yapper_start_process | Start a generation process (spends credits) | Live |
yapper_generate_speech | Legacy synchronous speech (may spend credits) | Live |
yapper_get_process | Poll one process | Live |
yapper_list_processes | List recent processes | Live |
yapper_list_assets | List generated or imported assets | Live |
yapper_get_asset | Fetch one asset | Live |
yapper_show_assets | Show assets in a numbered grid (widget hosts) | Live |
yapper_update_asset | Favorite an asset, or restore it from the trash | Live |
yapper_trash_asset | Move an asset to the trash (purged after 60 days) | Live |
yapper_import_asset | Import an external HTTP(S) asset | Live |
yapper_import_file | Import a file attached in ChatGPT | Live |
yapper_create_asset_upload | Create a hosted signed-upload ticket | Live |
yapper_complete_asset_upload | Finalize a hosted signed upload | Live |
yapper_upload_asset | Upload a local path in one call (local stdio only) | Live |
yapper_list_models | List available models and capabilities | Live |
yapper_get_model_schema | Fetch one model's authenticated input schema | Live |
yapper_list_audio_voices | List voices compatible with an audio model | Live |
yapper_list_sessions | List or search the team's sessions | Live |
yapper_get_session | Read one session and its web link | Live |
yapper_list_session_messages | Read a session's chat with the in-app Yapper agent | Live |
yapper_create_session | Create a session to group work | Live |
yapper_update_session | Rename a session or set its image | Live |
yapper_add_assets_to_session | Add existing assets to a session | Live |
yapper_remove_assets_from_session | Take media out of a session (keeps the assets) | Live |
yapper_get_workspace | List a session's folders, files, and unfiled media | Live |
yapper_read_workspace_item | Read a folder, a document's text, or an asset | Live |
yapper_create_workspace_folder | Create folders along a workspace path | Live |
yapper_write_workspace_document | Create or overwrite a text document or the brief | Live |
yapper_place_assets_in_workspace | File existing media into a workspace folder | Live |
yapper_update_workspace_item | Move, rename, pin, or annotate a workspace item | Live |
yapper_remove_workspace_item | Remove an item from the tree (keeps its assets) | Live |
yapper_get_canvas | Read a session's canvas: cards, wires, versions | Live |
yapper_get_canvas_node | Read one canvas card with every version | Live |
yapper_add_canvas_nodes | Add wired cards to a canvas | Live |
yapper_update_canvas_node | Edit a card's prompt, model, settings, or layout | Live |
yapper_update_canvas_nodes | Edit up to 100 cards at once (e.g. a re-layout) | Live |
yapper_remove_canvas_nodes | Remove cards and their wires | Live |
yapper_connect_canvas_nodes | Wire one card's output into another card | Live |
yapper_disconnect_canvas_nodes | Remove a wire between two cards | Live |
yapper_run_canvas | Run canvas cards in order (spends credits) | Live |
yapper_get_canvas_run | Check a canvas run's progress and outputs | Live |
yapper_cancel_canvas_run | Take queued cards out of a canvas run | Live |
yapper_get_timeline | Read a session's timeline and its fullscreen link | Live |
yapper_edit_timeline | Add, trim, and style clips, text, and transitions | Live |
yapper_caption_timeline | Caption a timeline's audio | Live |
yapper_get_editor | Read the Editor strip and its running edits | Live |
yapper_add_to_editor | Put images or videos in the Editor | Live |
yapper_remove_from_editor | Take items out of the Editor (keeps the assets) | Live |
yapper_get_app_link | Link to a session or tool, elements, or library | Live |
yapper_get_project_access | Read project access settings | Live |
yapper_update_project_access | Change project access or ownership | Live |
yapper_invite_to_project | Invite someone to a project by email | Live |
yapper_invite_to_workspace | Invite someone to the connected workspace | Live |
yapper_get_credits | Check team credit balance | Live |
yapper_get_usage | Team credits, member and API key credit limits | Live |
yapper_get_usage_breakdown | Credit spend by model and source over time | Live |
yapper_get_usage_cycle | This billing cycle's credits and the next refill | Live |
yapper_get_agent_usage | Included agent allowance and usage by model | Live |
yapper_list_usage_ledger | List individual credit charges and refunds | Live |
yapper_list_session_usage | List sessions with their all-time spend | Live |
yapper_list_member_usage | Spend per member (owner or admin connection) | Live |
yapper_list_members | Team members with their roles | Live |
yapper_get_storage_usage | Stored bytes and asset counts by type | Live |
yapper_show_credit_usage | Show the credit balance and refill (widget hosts) | Live |
yapper_show_credits | Show credits and packs to buy (widget hosts) | Live |
yapper_buy_credits | Buy a confirmed pack (credits widget only) | Live |
yapper_list_elements | List or search the workspace's elements | Live |
yapper_get_element | Read one element by id or @ID | Live |
yapper_create_element | Make an element from image assets | Live |
yapper_update_element | Rename, describe, or change an element's images | Live |
yapper_delete_element | Delete 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_creditsbefore expensive work when the user asks about feasibility. - Call
yapper_whoamibefore 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_processcalls. - Poll process status instead of assuming immediate completion, waiting the
returned
suggestedPollAfterSecondsbefore eachyapper_get_processcall. - Return asset ids and URLs from the public response shape only.
- Give the user the links the API returns (
webUrl, oryapper_get_app_linkfor 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.