---
title: "Use Zvid with ChatGPT and AI assistants"
canonical_url: https://docs.zvid.io/docs/ai-assistants/
source: docs/ai-assistants.md
content_revision: 6338386a1dd87e4a
---

# Use Zvid with ChatGPT and AI assistants

An assistant can help you write Zvid JSON using these public docs. To inspect your account, save a draft or render media, connect the assistant to Zvid's authenticated **MCP server**:

```text
https://mcp.zvid.io/mcp
```

Reading the website does not connect an account or start a render. If you only want JSON, give the assistant the [documentation index](https://docs.zvid.io/docs-index.md), [project reference](https://docs.zvid.io/docs/structure/) and [validation guide](https://docs.zvid.io/docs/validate-and-estimate/). Run the resulting request from your own server.

## Connect ChatGPT

You need a Zvid account and a ChatGPT account/workspace that allows custom MCP connections. Availability and administration settings can differ.

1. In ChatGPT, open **Settings → Security and login** and enable **Developer mode**, if available.
2. Open **Plugins**, use the add connection action, and enter `https://mcp.zvid.io/mcp` as the server URL.
3. Choose OAuth and complete the Zvid sign-in and consent screen. Do not paste an API key into a chat message.
4. Start with: **“Use Zvid to show my account and available tools. Do not render anything.”**

These ChatGPT steps were checked on 22 September 2026. Follow [OpenAI's connection instructions](https://developers.openai.com/api/docs/mcp#connect-in-chatgpt) if the labels differ in your client. A workspace administrator may control access to custom connections.

## Connect Codex

Codex is a separate client. Register the hosted server and authenticate:

```bash
codex mcp add zvid --url https://mcp.zvid.io/mcp
codex mcp login zvid
```

In a client that exposes MCP settings instead of a command line, enter the same server URL and complete OAuth there. See [Codex MCP configuration](https://learn.chatgpt.com/docs/extend/mcp) for client-specific options.

## Other MCP clients and n8n

Use a client that supports Streamable HTTP and OAuth. Zvid uses authorization code with PKCE and the `zvid:mcp` scope. For clients without OAuth, the hosted endpoint accepts an API key in the `x-api-key` header. Keep credentials in the client's credential settings.

In n8n, use the built-in **MCP Client Tool** against the hosted endpoint with an **MCP OAuth2 API** credential. The separate Zvid action and trigger nodes use API-key credentials; see [Integrations](https://docs.zvid.io/docs/integrations/).

## Choose the capabilities the assistant needs

| Profile | Intended use | Capabilities |
| --- | --- | --- |
| `readonly` | Account and result inspection | `get_account`, `list_media`, `get_media` |
| `creator` | Interactive creative work; default | Authoring/schema tools, library discovery, validation, projects/templates, reviewable drafts and approval-aware rendering |
| `automation` | Trusted automated workflows | Creator tools plus direct video/image rendering, bulk rendering and webhook tools |
| `developer` | API development | All registered tools; globally disabled operations remain unavailable |

The client discovers the actual available tools when it connects. A tool mentioned in another profile is not necessarily available in yours. Update/delete tools are disabled on the hosted MCP surface even where REST supports the underlying operation.

Your dashboard stores the default profile and credit ceiling. A connection can request a concrete profile and limit:

```text
https://mcp.zvid.io/mcp?profile=creator&maxRenderCredits=60
```

The dashboard ceiling still applies; requesting a higher value in the URL does not bypass it. Connection settings cannot be changed by the model inside a conversation. The fallback per-render ceiling is 120 credits; actual account settings may lower it. MCP bulk operations have their own item ceiling, normally 25, in addition to account limits.

## From a brief to a finished video

1. **Describe the outcome.** Give the aspect ratio, target duration, audience, text, brand colors and any assets you own.
2. **Inspect an example.** The assistant can use `plan_creative_video`, `find_matching_examples` and `start_from_example` to find a suitable starting point. It can also discover reusable creative assets and search Zvid's stock library.
3. **Check the current contract.** Use `get_project_schema` and the relevant `get_element_docs`. If the schema reports `live: false`, it is a bundled fallback; use remote validation before rendering.
4. **Validate the exact project.** Use `validate_project_json` with `remote: true`. Resolve errors and inspect layout warnings. Mechanical repairs from `repair_project_json` still need review and validation.
5. **Save a draft.** In Creator, `create_media` or the matching template/example draft tool saves a reviewable draft. Creating a draft does not render media or spend render credits. `create_media` and `revise_media` require the complete project payload.
6. **Review and approve.** Check the draft and quote. `render_media` requires the approved quote token; changing the project or allowing the quote to expire requires a fresh quote. The default quote lifetime is 15 minutes; use the returned expiry time for the actual deadline.
7. **Track the result.** Inspect `get_media` or the returned render job with `get_render`. Deliver the media link only when completion is confirmed. Report a failed job instead of presenting a draft as finished media.

Automation and Developer can expose direct render tools that spend credits without the Creator draft/quote flow. Direct REST rendering also submits immediately. Select the interface and approval behavior appropriate to your workflow.

## A useful first request

> Create a draft for a 15-second vertical product video. Use my supplied product image and these three benefits. Find a suitable example, validate the exact project against my account limits, and show the draft and estimated credits. Wait for my approval before rendering.

For a reusable template, ask the assistant to declare variable defaults, save the template and use the free template preview to inspect the resolved project. Preview validates data; it does not produce a video preview. See [Template basics](https://docs.zvid.io/docs/templates/template-basics/).

## When something goes wrong

| Symptom | Action |
| --- | --- |
| No Zvid tools appear | Check the exact endpoint, connection status and selected profile; reconnect after changing connection settings |
| OAuth fails | Complete sign-in again and confirm your workspace permits the connection; use [authentication troubleshooting](https://docs.zvid.io/docs/authentication/) |
| Validation fails | Correct the returned field paths and account limits; avoid repeated paid submissions |
| Quote expired or project changed | Review a fresh draft/quote before approving |
| Credit ceiling reached | Reduce the requested work or deliberately change connection/account settings |
| Render failed | Inspect the returned reason and [render troubleshooting](https://docs.zvid.io/docs/operations/errors-and-retries/) |

For precise machine-readable context, use [Documentation resources](https://docs.zvid.io/docs/documentation-resources/). For account help, contact us at [https://zvid.io/contact](https://zvid.io/contact).