# Chat Assistant
Source: https://developers.gotolstoy.com/javascript-sdk/chat-assistant
Programmatically open, close, and observe the Tolstoy AI chat assistant bubble from your site.
The chat assistant exposes a JS API on `window.tolstoyAssistant` once the Tolstoy widget script has loaded. Use it to open, close, minimize, or observe the assistant modal from your own UI (custom CTAs, product pages, exit-intent triggers, etc.).
The API only controls the assistant modal state. The assistant must already be installed and enabled on the store. If the chat bubble is not rendered on the page, state changes are still tracked but have no visual effect.
## open()
Open the assistant modal.
```javascript theme={null}
window.tolstoyAssistant.open();
```
## close()
Close the assistant modal. The bubble stays visible (unless configured to hide on close).
```javascript theme={null}
window.tolstoyAssistant.close();
```
## minimize()
Minimize the assistant modal. The bubble stays visible; the conversation is preserved.
```javascript theme={null}
window.tolstoyAssistant.minimize();
```
## isOpen()
Returns `true` when the assistant modal is currently open.
```javascript theme={null}
if (!window.tolstoyAssistant.isOpen()) {
window.tolstoyAssistant.open();
}
```
## getState()
Returns the current assistant state.
```javascript theme={null}
const state = window.tolstoyAssistant.getState();
```
## subscribe(listener)
Subscribe to state changes. Returns an unsubscribe function.
Called every time the assistant state changes.
```javascript theme={null}
const unsubscribe = window.tolstoyAssistant.subscribe((state) => {
console.log("Assistant state:", state);
});
// Later, to stop listening:
unsubscribe();
```
## Waiting for the API
The Tolstoy script may not be ready on first paint. Guard with a small polling helper when binding from your own page scripts:
```javascript theme={null}
function withTolstoyAssistant(callback) {
if (window.tolstoyAssistant) return callback(window.tolstoyAssistant);
const id = setInterval(() => {
if (window.tolstoyAssistant) {
clearInterval(id);
callback(window.tolstoyAssistant);
}
}, 100);
}
withTolstoyAssistant((assistant) => assistant.open());
```
# Configuration
Source: https://developers.gotolstoy.com/javascript-sdk/configuration
Learn how to configure your Tolstoy widget to perform different functions on your site.
## Methods
### closePlayer()
Close the expanded Tolstoy Player
```javascript theme={null}
window.tolstoyWidget.closePlayer();
```
# Cookie Consent
Source: https://developers.gotolstoy.com/javascript-sdk/cookie-consent
This document explains how the Tolstoy Widget handles cookie consent, how it integrates with Shopify’s Customer Privacy API, and how to control acceptance or rejection programmatically.
### How Tolstoy Handles Consent with Shopify
When Tolstoy runs on a Shopify store:
* If **Shopify’s Customer Privacy API** is present, Tolstoy follows [Shopify’s analytics consent state](https://shopify.dev/docs/api/customer-privacy#check-consent-given).
* Analytics will be **allowed** when Shopify’s analytics state is anything other than 'no'.
* Analytics will be **blocked** when Shopify’s analytics state is 'no'.
* If Shopify’s API is **not** present, Tolstoy allows analytics by default unless you explicitly default to reject (see last section).
### Reject Cookie Conset programmatically
You can programmatically reject cookies when a user doenst accept analytics cooikes policy like this:
**Reject Policy:**
```javascript theme={null}
window.tolstoyWidget?.postMessage({ eventName: 'tolstoy_reject_cookie_policy' });
```
### Default Reject (No Cookies Until Accept)
If you want Tolstoy to start in a **rejected** state until the user explicitly accepts, set the following before loading the Tolstoy widget script:
```javascript theme={null}
localStorage.setItem('tolstoy-cookie-policy', 'rejected');
```
Then when a user accpets policy send this:
```javascript theme={null}
window.tolstoyWidget?.postMessage({ eventName: 'tolstoy_accept_cookie_policy' });
```
# Events
Source: https://developers.gotolstoy.com/javascript-sdk/events
Subscribe to JS events from your Tolstoy Widget or Embedded Player
Tolstoy's player uses `window.postMessage()` to post event from the embedded iframe to the parent hosting site, for more information see [Window.postMessage()](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage)
Example of using an event:
```javascript theme={null}
window.addEventListener("message", (message) => {
if (message.data.name === "tolstoyStarted") {
console.log("Tolsoty Started", message.data);
}
});
```
All events will send the event name in the `name` attribute, In addition all events will send:
* `accountId` - Your account ID
* `projectId` - Your project ID
* `anonymousId` - Viewer ID
## Core Events
| Event Name | Description |
| ------------------------- | --------------------------------------- |
| `tolstoyStarted` | Start button clicked for the first time |
| `pageView` | Page viewed |
| `embedView` | Element in view |
| `videoLoaded` | Video starts to play |
| `videoPause` | Video paused |
| `videoResume` | Video resumed |
| `videoReplay` | Video replayed |
| `videoSeeked` | Video seeked |
| `videoUnmuted` | Video unmuted |
| `videoWatched` | Video watched completion event |
| `feedPlay` | Feed started playing |
| `feedPause` | Feed paused |
| `feedScroll` | Swipe to next video |
| `clickViewProduct` | Click to view product details |
| `shareClick` | Share clicked |
| `tolstoyProductCardClick` | Product card clicked |
| `tolstoyAddToCart` | Add to cart triggered |
## Widget Lifecycle Events
| Event Name | Description |
| -------------------- | ------------- |
| `tolstoyWidgetReady` | Widget ready |
| `tolstoyWidgetOpen` | Widget opened |
| `tolstoyWidgetClose` | Widget closed |
| `tolstoyModalClose` | Modal closed |
## Interactive Events
| Event Name | Description |
| ----------------------- | -------------------- |
| `tolstoyAnswerClicked` | CTA button clicked |
| `tolstoyInputSubmit` | Form input submitted |
| `tolstoyLeadFormSubmit` | Lead form submitted |
| `tolstoyReachedEnd` | User reached end |
# Installation
Source: https://developers.gotolstoy.com/javascript-sdk/installation
Learn how to install the Tolstoy Widget on your site.
## Tolstoy Widget Code
Add the following script at the head on your site:
Replace `{{APP_KEY}}` with your account App Key.
```javascript theme={null}
```
For Shopify users the script is added automatically using the ScriptTag API
# Product update
Source: https://developers.gotolstoy.com/javascript-sdk/product-update
# Product Update Guide
When updating product information through the API, especially when dealing with variants, there are specific rules that must be followed to ensure successful updates.
## Key Rules for Variant Updates
1. **Maintain Original Order**: The variants array must maintain the exact same order as received from Shopify
2. **Complete Array Required**: You must provide the entire variants array, even when updating a single variant
3. **Position Matters**: Each variant must remain in its original position in the array
## Allowed Fields
### Product Fields
You can only update these fields for products:
* `id`
* `description_html` (or `descriptionHtml` for backward compatibility)
* `variants`
* `price`
* `compare_at_price`
* `title`
### Variant Fields
You can only update these fields for variants:
* `id`
* `price`
* `compare_at_price`
* `title`
## Examples
### ❌ Incorrect Approach
This will not work - sending only the variant you want to update:
```javascript theme={null}
window.tolstoyWidget.postMessage({
product: {
id: "prod_123",
variants: [
{
id: "var_2", // Second variant
price: 29.99,
},
],
},
eventName: "tolstoy_product_update",
});
```
### ✅ Correct Approach
Do this - send all variants in their original order:
```javascript theme={null}
window.tolstoyWidget.postMessage({
product: {
id: "prod_123",
title: "Updated Product Title",
description_html: "New product description
",
variants: [
{
id: "var_1", // Include first variant even if unchanged
},
{
id: "var_2",
price: 29.99, // Your update here
},
{
id: "var_3", // Include third variant even if unchanged
},
],
},
eventName: "tolstoy_product_update",
});
```
## Important Notes
* **Variant Order**: Must exactly match what you received from Shopify
* **All Variants Required**: Include all variants in the array, even ones you're not updating
* **Minimal Updates**: For unchanged variants, you only need to include their `id`
* **Field Validation**: Including fields not listed in the allowed fields will cause the update to fail
## Best Practice Example
Here's a complete example showing how to properly update a variant:
```javascript theme={null}
// Original product from Shopify has 3 variants
const originalVariants = [
{ id: "var_1", title: "Small", price: 19.99 },
{ id: "var_2", title: "Medium", price: 19.99 },
{ id: "var_3", title: "Large", price: 19.99 },
];
// To update product title and medium variant's price
window.tolstoyWidget.postMessage({
product: {
id: "prod_123",
title: "Updated Product Name",
variants: [
{ id: "var_1" }, // Keep first variant
{ id: "var_2", price: 24.99, title: "Medium Updated" }, // Update second variant
{ id: "var_3" }, // Keep third variant
],
},
eventName: "tolstoy_product_update",
});
```
## Request product update
Async products update can be made with tolstoy\_request\_products\_update event. This could be used for example after language change:
```javascript theme={null}
const handle = '{{ product.handle }}';
window.tolstoyWidget.postMessage({
eventName: 'tolstoy_request_products_update',
handles: [handle],
});
```
# Stories
Source: https://developers.gotolstoy.com/javascript-sdk/stories
Tolstoy Stories extra options
### Standard Usage
Use this script in case you want to make the stories relaunch and get it by new product id:
Replace `{{PUBLISH_ID}}` with your project publish id.
Replace `{{PRODUCT_ID}}` with your product id.
Replace `{{VARIANT_ID}}` with your variant id to sort the videos by the variant id (works if videos were tagged with variants and not just the product).
```javascript theme={null}
window.tolstoyWidget?.['{{PUBLISH_ID}}']?.init('{{PROUDUCT_ID}},{{VARIANT_ID}}')
```
### Enhanced Usage with Data-Tag Support
or hybrid collection/product pages where you need to update both product ID and Shopify tags:
Replace `{{SHOPIFY_TAGS}}` with one or comma seperated list of shopify tags.
```
window.tolstoyWidget?.['{{PUBLISH_ID}}']?.init({
productId: '{{PRODUCT_ID}}',
tags: '{{SHOPIFY_TAGS}}'
});
```
# Subscriptions
Source: https://developers.gotolstoy.com/javascript-sdk/subscriptions
Learn how to subscribe to events fired by Tolstoy widget.
## Before you dive in
Check if `window.tolstoyWidget` is already initialized or wait for the `tolstoyWidgetReady` event before doing anything. This will make sure Tolstoy's widget is set for action:
```javascript theme={null}
if (window.tolstoyWidget) {
// Your next steps go here
} else {
window.addEventListener("tolstoyWidgetReady", () => {
// Your next steps go here
});
}
```
## Product card click
The "product card" is a component shown on a Swipeable Tolstoy's mobile layout
![product_card_preview]()
It's possible to subscribe to the components' `onClick` event like so:
```javascript theme={null}
const subscribeToTolstoyProductCardClick = () => {
const myCallback = (payload) => {
// Your logic here
};
const options = {};
window.tolstoyWidget.subscribe(
"tolstoy_product_card_click",
myCallback,
options
);
};
if (window.tolstoyWidget) {
subscribeToTolstoyProductCardClick();
} else {
window.addEventListener("tolstoyWidgetReady", () => {
subscribeToTolstoyProductCardClick();
// Additional logic...
});
}
```
📌 *When done correctly, `Subscribe to event tolstoy_product_card_click` will appear in your logs.*
### Callback
Once the event is fired, `myCallback` will be triggered with the following payload:
```javascript theme={null}
{
eventName: "tolstoy_product_card_click",
productId, // Product ID of the specific product that has been clicked
taggedProductIds, // A list of Product IDs that are tagged on the video, including productId
variantId, // Will be passed if a variant was specifically tagged
}
```
### Options
By default, subscribing to the `tolstoy_product_card_click` event prevents the product modal from opening:
![product_modal_preview]()
If you'd still like the product modal to open, you can pass the following option to `window.tolstoyWidget.subscribe`:
```javascript theme={null}
const options = {
disableProductModal: false, // true by default
};
```
## Add to cart
The "Add to cart" button is shown in the product modal:
![product_modal_preview]()
It's possible to subscribe to button's `onClick` event like so:
```javascript theme={null}
const subscribeToTolstoyAddToCartClick = () => {
const myCallback = (payload) => {
// Your logic here
};
const options = {};
window.tolstoyWidget.subscribe("tolstoy_add_to_cart", myCallback, options);
};
if (window.tolstoyWidget) {
subscribeToTolstoyAddToCartClick();
} else {
window.addEventListener("tolstoyWidgetReady", () => {
subscribeToTolstoyAddToCartClick();
// Additional logic...
});
}
```
📌 *When done correctly, `Subscribe to event tolstoy_add_to_cart` will appear in your logs.*
### Callback
Once the event is fired, `myCallback` will be triggered with the following payload:
```javascript theme={null}
{
eventName: "tolstoy_add_to_cart",
productId,
variantId,
}
```
#### Report Add to cart Success or Failure
* **Success Scenario** (product added successfully to the cart)
```javascript theme={null}
const myCallback = (payload) => {
const { variantId } = payload;
// Your add to cart logic here
window.tolstoyWidget.postMessage({
...payload, // Make sure to include this line
eventName: "tolstoy_add_to_cart_success",
});
};
```
* **Failure/Error Scenario**
```javascript theme={null}
const myCallback = (payload) => {
const { variantId } = payload;
// Your add to cart logic here
window.tolstoyWidget.postMessage({
...payload, // Make sure to include this line
eventName: "tolstoy_add_to_cart_error",
description: "itemSoldOut", // Optional description
});
};
```
🛈 Note 1: Tolstoy expects some data from `payload` to be sent back within the message, so make sure to spread `payload` in your message.
🛈 Note 2: The `description` field is optional. Use it to specify an error like `itemSoldOut`. If you skip it, you'll get a general "Error adding to cart" message.
## Unsubscribing from an event
If you'd like to stop listening to an event, you can do it like so:
```javascript theme={null}
window.tolstoyWidget.unsubscribe(eventName, myCallback);
```
🛈 Note: `myCallback` should be the original callback passed to `window.tolstoyWidget.subscribe`
# Widget (Bubble)
Source: https://developers.gotolstoy.com/javascript-sdk/widget
Learn how to configure your Tolstoy widget to perform different functions on your site.
## Settings
We support the following additional configurations for the floating widget:
In case a user closed the widget and you want to keep showing it to him.
Load the widget without showing it.
Stop the preview window from endlessly looping.
No option to close the widget.
Add the following code to the page in order to set the settings:
```javascript theme={null}
window.tolstoySettings = {
alwaysShow: true,
loadHidden: true,
stopPreviewLoop: true,
noCloseOption: true,
};
```
## start()
Start the widget, open it expanded and plays immediately
```javascript theme={null}
window.tolstoyWidget.start();
```
## startPart(partNumber)
Start the widget at a specific part number, open it expanded and plays immediately. If the widget is already open it will start to play the given part.
```javascript theme={null}
window.tolstoyWidget.startPart(partNumber);
```
## show()
Show the widget bubble if it was loaded hidden or closed
```javascript theme={null}
window.tolstoyWidget.show();
```
### hide()
Hide the widget bubble from screen
```javascript theme={null}
window.tolstoyWidget.hide();
```
## recreate(tolstoyWidgetId, settings)
Load a new widget with a different Tolstoy Id, remember to replace the
```javascript theme={null}
window.tolstoyWidget.recreate("{{TOLSTOY_ID}}");
```
## on(eventType, callback)
Trigger a callback on a specific event
Params:
**Supported events**:
onWidgetOpen - triggers when the widget is opened \\
onWidgetClose - triggers when the widget is closed \\
onWidgetReady - triggers when the widget is ready \\
onTolstoyClose - triggers when the tolstoy bubble is closed
A function to trigger
```javascript theme={null}
window.tolstoyWidget.on("onWidgetOpen", () => {
console.log("Widget Opened");
});
```
# Connect a client
Source: https://developers.gotolstoy.com/mcp/connect
Add the Tolstoy MCP servers to ChatGPT, Claude, Cursor, and other AI clients.
Every Tolstoy MCP connection uses OAuth 2.1 — there are no API keys. Add the server URL, then sign in with your Tolstoy account when prompted. The connection is bound to that workspace.
Use whichever server you need (you can add both):
* **Tolstoy Library** — `https://apilb.gotolstoy.com/mcp/v1/library/mcp`
* **Tolstoy Studio** — `https://apilb.gotolstoy.com/mcp/v1/mcp`
Per-client setup is also available inside the Tolstoy platform under **Settings → MCP**, with a copy-paste URL and step-by-step guide for each client.
## ChatGPT
Tolstoy Library is a published **ChatGPT app** — the easiest path:
1. In ChatGPT, search apps for **Tolstoy Library**.
2. Click **Connect** and sign in with your Tolstoy account.
3. Ask ChatGPT about your library, widgets, products, or ads — it uses the tools, with interactive views inline.
To add the Studio server (or Library via URL), enable **Settings → Apps & Connectors → Advanced → Developer mode**, then add a connector with the endpoint above.
## Claude
1. Open **Settings → Connectors** in the Claude app or on claude.ai.
2. **Add custom connector**, name it `Tolstoy Library` (or `Tolstoy Studio`), and paste the endpoint.
3. Click **Connect**, sign in with your Tolstoy account.
## Cursor
Add a remote MCP server in Cursor's MCP settings with the endpoint above; the first tool call opens an OAuth tab to sign in.
## CLI clients
```bash theme={null}
# Claude Code
claude mcp add --transport http tolstoy-library https://apilb.gotolstoy.com/mcp/v1/library/mcp
claude mcp add --transport http tolstoy-studio https://apilb.gotolstoy.com/mcp/v1/mcp
# Gemini CLI
gemini mcp add --transport http tolstoy-library https://apilb.gotolstoy.com/mcp/v1/library/mcp
```
### Codex CLI
Codex CLI's `codex mcp add` targets STDIO servers, so add the remote server to `~/.codex/config.toml` directly, then run the OAuth login:
```toml theme={null}
[mcp_servers.tolstoy-library]
url = "https://apilb.gotolstoy.com/mcp/v1/library/mcp"
[mcp_servers.tolstoy-studio]
url = "https://apilb.gotolstoy.com/mcp/v1/mcp"
```
```bash theme={null}
codex mcp login tolstoy-library
```
The first login opens a browser tab to sign in with your Tolstoy account; the token is cached for future sessions. Repeat `codex mcp login tolstoy-studio` if you added the Studio server too.
## Generic config
Most clients accept a JSON config like:
```json theme={null}
{
"mcpServers": {
"tolstoy-library": { "url": "https://apilb.gotolstoy.com/mcp/v1/library/mcp" },
"tolstoy-studio": { "url": "https://apilb.gotolstoy.com/mcp/v1/mcp" }
}
}
```
## Open source
The server definitions and an always-current tool list live in the [GoTolstoy/mcp](https://github.com/GoTolstoy/mcp) repo. Agent skills that teach clients the shoppable-video workflows are in [GoTolstoy/agent-skills](https://github.com/GoTolstoy/agent-skills).
# Tolstoy Library
Source: https://developers.gotolstoy.com/mcp/library
Run your shoppable video workspace from chat — media library, shoppable widgets, product tagging, multi-store, and Meta ads.
The **Tolstoy Library** MCP server turns any AI client into a control surface for your shoppable video workspace.
```
https://apilb.gotolstoy.com/mcp/v1/library/mcp
```
See [Connect a client](/mcp/connect) to add it. The tools below are grouped by what they manage.
## Media assets
Your library of videos, images, social imports, and AI Studio drafts.
| Tool | What it does |
| --------------- | -------------------------------------------------------------------------------------------------- |
| `list_assets` | List your most recent library assets, with optional type and favorite filters. |
| `search_assets` | Search the library by query (name, UGC creator). |
| `get_asset` | Fetch full details for one or more assets, including tagged products, playlists, and Shopify tags. |
| `update_asset` | Rename an asset or toggle its favorite status. |
## Shoppable widgets
Onsite video widgets shoppers see on your storefront — Stories, Carousel, Spotlight, For You Feed, Tile, Collection Grid, and Bubble Feed.
| Tool | What it does |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `list_widgets` | List your onsite shoppable widgets, live or draft, with type and status. |
| `get_widget` | Inspect a widget: type, live status, content selection, and the actual videos it shows — pass a `productId` to preview a specific product page. |
| `create_widget` | Create a new shoppable widget from a template, with the platform's defaults. |
| `update_widget` | Rename, publish/unpublish, toggle PDP mode, or replace a widget's content selection. |
Setting a widget live activates it in Tolstoy; appearing on the storefront also needs the Tolstoy app embed enabled in your Shopify theme (a one-time setup per store). The publish result returns the exact steps.
## Products & shoppability
Make videos shoppable by tagging store products on them.
| Tool | What it does |
| ------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `search_products` | Find a store product by title to get its product id. |
| `tag_video_product` | Tag (or untag) products on a video — tagged videos feed product-tagged playlists and show on those products' pages. |
## Stores
| Tool | What it does |
| ------------- | ------------------------------------------------------------------------------------------------- |
| `list_stores` | List the connected stores on your account. Widget, product, and ads tools can target any of them. |
## Paid ads
Read-only insight and creative upload for Meta ads — no tool moves ad spend.
| Tool | What it does |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `list_ad_campaigns` | List your Meta ad campaigns with real delivery status (not just paused/active). |
| `get_ads_performance` | Meta ads performance — spend, ROAS, CTR, purchases — per campaign, ad set, or ad. |
| `publish_to_meta_ads_library` | Push a library video or image into Meta Ads Manager, ready for ad creation. No campaign or spend is created. |
## Example: make a video shoppable end to end
> "Make my unboxing video shoppable for the DBTK 1 shirt, put it in a Stories widget, publish it, and show me how my ads are doing."
1. `search_assets` → find the unboxing video.
2. `search_products` → find DBTK 1's product id.
3. `tag_video_product` → tag the product on the video.
4. `create_widget` → a Stories widget (starts as a draft).
5. `get_widget` with the product id → confirm the video shows on that product's page.
6. `update_widget` with `live: true` → publish, then follow the returned app-embed steps.
7. `get_ads_performance` → check spend and ROAS.
# Overview
Source: https://developers.gotolstoy.com/mcp/overview
Connect any AI client to Tolstoy and run your shoppable video workspace from chat — via the Model Context Protocol (MCP).
Tolstoy exposes its platform to AI clients over the **Model Context Protocol (MCP)** — the open standard for connecting assistants like Claude, ChatGPT, and Cursor to external tools. Connect once, then run your **shoppable video** workspace right from chat: generate content, manage your media library, build and publish shoppable widgets, tag products, and track ad performance.
There are **two remote MCP servers**, both served over Streamable HTTP and secured with OAuth 2.1 + PKCE. There are no API keys to paste — your client runs the OAuth sign-in on first connect, and the connection is bound to the Tolstoy workspace you authorize with.
| Server | Endpoint | What it does |
| ------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Tolstoy Library** | `https://apilb.gotolstoy.com/mcp/v1/library/mcp` | Run your shoppable video workspace — media library, shoppable widgets (Stories, Carousel, Spotlight), product tagging, multi-store, and Meta ads. |
| **Tolstoy Studio** | `https://apilb.gotolstoy.com/mcp/v1/mcp` | Generate and iterate on marketing videos and images with Tolstoy Studio's AI creative director. |
Step-by-step setup for ChatGPT, Claude, Cursor, and more.
Assets, shoppable widgets, products, stores, and ads.
Generate and iterate on videos and images.
Published as io.github.GoTolstoy/library and /studio.
## Authentication
OAuth 2.1 with PKCE, backed by Amazon Cognito. Clients discover the flow via RFC 9728 protected-resource metadata at each server's `/.well-known` endpoints — there is nothing to configure beyond adding the server URL and signing in.
Each connection operates on the Tolstoy workspace you sign in with. Accounts with multiple stores can target any connected store from the widget, product, and ads tools.
## App-aware clients
In clients that support interactive MCP apps (ChatGPT, Claude), tool results render as inline views — a shoppable-widget card grid, asset previews, and widget detail with the actual videos a widget shows. Plain clients receive the same data as text, so every tool works everywhere.
## Get started
The fastest path is the published **Tolstoy Library** app in ChatGPT — search "Tolstoy Library" and click Connect. For every other client, see [Connect a client](/mcp/connect). Per-client setup is also available in the Tolstoy platform under **Settings → MCP**.
# Tolstoy Studio
Source: https://developers.gotolstoy.com/mcp/studio
Generate and iterate on marketing videos and images in chat with Tolstoy Studio's AI creative director.
The **Tolstoy Studio** MCP server lets an AI client create marketing content — product videos and images for shoppable experiences, social/UGC, and ads — using Tolstoy Studio's creative-director agent server-side.
```
https://apilb.gotolstoy.com/mcp/v1/mcp
```
See [Connect a client](/mcp/connect) to add it.
## Tools
| Tool | What it does |
| ------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `generate_studio_content` | Start a new Studio generation (image or video) from a prompt, optional reference images, and an aspect ratio. |
| `iterate_studio_content` | Continue and refine an existing Studio generation in the same session. |
## Working principle
Tolstoy Studio runs a full creative-director agent server-side — scriptwriting, model casting, and brand-safe generation. Pass the user's intent directly and pick the output format (`assetType`, `aspectRatio`); refine with `iterate_studio_content` reusing the session rather than regenerating from scratch.
Content generated in Studio lands in your Tolstoy library, where the [Tolstoy Library](/mcp/library) tools can tag products on it, drop it into a shoppable widget, or push it to your Meta ads library.
# Welcome
Source: https://developers.gotolstoy.com/welcome
Use our API to programmatically create new accounts, upload and respond to Tolstoys, and so much more.
We're excited for you to leverage Tolstoy's robust API to build new functionality for your app or service!
Is there another way you'd like to leverage Tolstoy's API that we don't currently support? Let us know at [support@gotolstoy.com](mailto:support@gotolstoy.com) and we'll launch it for you ASAP.