# Your AI agent (MCP)

> Connect your AI agent to the Ondaclip MCP server so Claude Code, Cursor, Antigravity or OpenCode can write, check, fix and film your tutorials.

Ondaclip has an **MCP server**. Your AI agent already works in your app's
code, and through MCP it can drive Ondaclip too: write a tutorial, check that
it plays on your app, see what broke and why, fix it, and film it.

It works with **any agent that supports MCP**: Claude Code, OpenCode,
Antigravity, Cursor and more. Bring the agent and model you already use.

## What your agent can do

| Tool | What it does |
|---|---|
| `list_products` | The products your token can access, your role, and their languages and demo accounts |
| `readiness` | Is the product ready to film? Lists each check, and what to do next when one fails |
| `list_tutorials` | The published tutorials, by chapter, and whether each one still matches the app |
| `list_problems` | What broke: the tutorial, the step and the cause, in plain language |
| `validate_config` | Checks `.ondaclip/config.yaml` before you commit it, and shows what each product in a monorepo gets (`products:`) |
| `validate_publication` | Checks `.ondaclip/publication.yaml`: languages, chapters, and tutorials with no file |
| `validate_tutorial` | Checks a tutorial file before you commit it |
| `check` | Plays tutorials on your app at a branch, without filming (takes a few minutes). `learn: true` logs the requests your settings don't allow yet and suggests `allowedWrites` and `writes:` |
| `run_status` | Tracks a check or a shoot until it finishes |
| `film` | Films tutorials: capture, narration in every language, editing |
| `add_product` | Admin token: adds a product to your workspace. The response gives the next setup step |
| `setup_product` | Admin token: runs one setup step (repository; where it runs, with `cloud` for Ondaclip Cloud or `gcp` for your infrastructure; app; assistant; check; connect) and returns the next one. Steps that need a person come with a studio link |
| `set_aside` | Sets a new tutorial aside (not filmed for now, with a reason), or brings it back |
| `update_product` | Admin token: changes the product's Ondaclip version, its working branch, or its name in `products:` |
| `set_demo_account` | Admin token: saves the product's demo accounts (they can never be read back) |
| `publish` | Publishes the new videos once a person has approved every clip in the studio. Otherwise, it returns the review link |
| `decide_problem` | Marks a problem as a bug, an intended change, or not a problem |
| `look_at_tutorial` | Shows a tutorial as Ondaclip filmed it: each step with its narration and an image (the newest shoot, or the published video), so your agent can check it before a person reviews |
| `look_at_change` | Shows each screen a change check found different, with the changed area boxed in red |
| `list_review_notes` | What reviewers rejected and why, so your agent fixes the tutorial after a review |
| `report_problem` | Records a bug or a video defect your agent saw, for a person to decide |
| `scan_app` | Every screen of the app, whether a tutorial films it, and the elements that have no id yet |
| `propose_testids` | Adds the missing element ids as a draft pull request |
| `voices` | The narration voices of the product, the voices available, and a pull request to change them |
| `integration` | Where the published videos are and the code that shows them in your app |
| `stop_run` | Stops a check or a shoot started by mistake |

Review stays in the studio, with a person. Your agent never approves a clip,
and it only publishes what a person has approved. Every response includes the
studio link to share with that person. An **admin** token (personal only, and
never with more access than you have) lets your agent handle setup tasks: the
version, the branch, the demo accounts.

Every call follows the same rules as the studio: your role, your token's
products, your plan, and the environment your product is filmed on (DEV).

## Set it up

### 1. Create a personal token

In the studio, go to the **API** page, then **My personal tokens**, **New
token**. Give it a name (the agent), the **Producer** role, the products in
this repository, and a lifetime of 7 to 365 days. Copy the token right away:
Ondaclip only shows it once.

Keep it out of your repository by storing it in an environment variable, for
example `ONDACLIP_TOKEN`.

### 2. Add the server to your agent

The server is `https://studio.ondaclip.com/mcp` (streamable HTTP), with the
header `Authorization: Bearer <your token>`.

**Claude Code**

```bash
claude mcp add --transport http ondaclip https://studio.ondaclip.com/mcp \
  --header "Authorization: Bearer $ONDACLIP_TOKEN"
```

**Antigravity (agy)**

```bash
agy mcp add --header "Authorization: Bearer $ONDACLIP_TOKEN" ondaclip https://studio.ondaclip.com/mcp
```

**OpenCode** (`opencode.json` in the repository)

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "ondaclip": {
      "type": "remote",
      "url": "https://studio.ondaclip.com/mcp",
      "headers": { "Authorization": "Bearer {env:ONDACLIP_TOKEN}" }
    }
  }
}
```

**Cursor** (`.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "ondaclip": {
      "url": "https://studio.ondaclip.com/mcp",
      "headers": { "Authorization": "Bearer ${env:ONDACLIP_TOKEN}" }
    }
  }
}
```

**Other agents**: give it the URL and header above. Ondaclip serves MCP over
streamable HTTP.

### 3. Give your agent the Ondaclip skill

The skill teaches your agent how to write a good tutorial, name its
`data-ondaclip-id` attributes, read a problem and fix it. It's included with
the Team and Business plans. Ask us at [hello@ondaclip.com](mailto:hello@ondaclip.com).

### 4. Tell your agent how to change `.ondaclip/`

Paste this into your repository's `AGENTS.md` (or `CLAUDE.md`):

```markdown
## Ondaclip (video tutorials)
- `.ondaclip/` holds the video tutorials of this repository. Before you change it,
  read https://ondaclip.com/docs/ondaclip-folder/ and the page of the file you change.
- Change only what is asked; never put a secret in it.
- Check every file before you commit: the Ondaclip MCP tools validate_config,
  validate_tutorial, validate_publication (or the JSON schemas of the docs).
- A new tutorial: find the screens in the code, add the missing data-ondaclip-id
  (<area>-<element>-<kind>, only the attributes), write .ondaclip/tutorials/<id>.yaml,
  validate_tutorial, push a branch, check it, fix, then one pull request with the ids
  and the tutorial. Rules: https://ondaclip.com/docs/for-ai-agents/#from-a-need-to-a-pull-request
- Push on a branch and open a pull request; a person reviews the videos in the studio.
```

## From a need to a pull request

Your agent knows your code, and Ondaclip knows how to film it. Starting from
a request in your own words ("a video on how to invite a colleague"), your
agent:

1. finds the product (`list_products`) and checks that it's ready (`readiness`);
2. finds the task's screens in the code: routes, menu, page components;
3. adds any missing `data-ondaclip-id` to the elements the video shows, clicks or types into (`<area>-<element>-<kind>`; only the attributes, nothing else on those lines);
4. writes `.ondaclip/tutorials/<id>.yaml` and runs `validate_tutorial`;
5. pushes a branch and runs `check` on it (tracked with `run_status`), reads `list_problems` and fixes what broke;
6. opens **a single pull request** with the ids, the tutorial and the check result.

The rules it follows: read-only by default (a tutorial that saves data lists
its `writes` and has a `cleanup`), fictitious data only (`safeEmail`,
`neverShow`, `hide`, files in `.ondaclip/fixtures/`), every text in every
language of the product, one action per shot, and clips of 50 seconds at
most. In a repository with several products, it writes to its own product's
folder (`folder` in `list_products`). The ids it adds show up in the app once
the branch is deployed to the environment Ondaclip films (DEV by default).

## Ask your agent

- "Add an Ondaclip tutorial for inviting a colleague, then check it on this branch."
- "This pull request changes the orders page: check the Ondaclip tutorials it touches and fix the ones that break."
- "Read the open Ondaclip problems and tell me which ones are bugs in the app."
- "Film the tutorials on this branch."

## Good to know

- Your agent pushes its changes to a branch, and Ondaclip reads the tutorials from that branch.
- A check takes a few minutes and counts toward your plan's runs, just like a check from the studio.
- Revoke a token on the API page. It stops working immediately.

Source: https://ondaclip.com/docs/for-ai-agents/