> ## Documentation Index
> Fetch the complete documentation index at: https://docs.myunite.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP for AI agents

> Connect Claude, ChatGPT and Claude Code to Unite with your account, or any agent with an API key.

The Unite MCP server lets an AI agent use Ad Score:

* check the catalog and the quota;
* upload a creative;
* create and follow pre-tests;
* read the result and download the PDF.

It follows the same scopes, the same limits and the same error codes as the API.

To get both the connector and the Unite skills, [install the Unite plugin](#install-the-unite-plugin).

> [card] [Claude](https://claude.ai/customize/connectors?modal=add-custom-connector\&connectorName=Unite\&connectorUrl=https%3A%2F%2Fmcp.myunite.ai%2Fmcp)
>
> Opens Claude with the Unite connector already filled in. Click Continue, Add and Connect.

> [card] [ChatGPT](https://chatgpt.com/plugins)
>
> Opens ChatGPT Plugins. Click Add › Add custom MCP server and paste the address.

> [card] [Claude Code](#connect)
>
> One terminal command and a browser login.

Address to paste:

```text theme={null}
https://mcp.myunite.ai/mcp
```

On the Unite page that opens, sign in as usual and click **Autorizar** (Authorize). You choose the workspace in the conversation.

Once connected, [try it in Claude](https://claude.ai/new?q=Use%20Unite%20and%20tell%20me%20how%20much%20pre-test%20quota%20the%20workspace%20has.): the chat opens with the request typed, and you just send it.

## Install the Unite plugin

The plugin, version 1.3.0, installs the connector and two skills together. The connector retrieves results. The `unite:ad-score` skill helps run, read and present pre-tests in the format you ask for. The `unite:brand-guidelines` skill helps save the workspace brand. They are the same [Unite guides](#unite-guides) the connector serves.

* **Claude.** On a paid plan that allows plugin installation in your workspace, download the [Claude plugin](https://myunite.ai/home/plugins/unite.plugin). Open **Customize › Plugins**, choose the custom plugin upload option and select `unite.plugin`.
* **ChatGPT on the web.** Download the [ChatGPT plugin](https://myunite.ai/home/plugins/unite-chatgpt.zip). A workspace administrator with upload access selects the workspace in the **Admin console**, opens **Plugins › Add › Upload plugin**, and uploads the ZIP. If the administrator chooses **Available**, each person opens the plugin and selects **Install plugin**. With **Installed**, the selected people get it automatically.

After installing in your app, open the Unite connection and sign in. You choose the workspace that holds your pre-tests in the conversation.

If your ChatGPT workspace already uses a custom Unite connector and a new option is missing, an administrator can refresh its tools in the workspace app settings, review the changes and publish the update. [Updating an existing ChatGPT connection](https://help.openai.com/en/articles/12584461-connecting-custom-mcp-servers-in-chatgpt)

Try “What score did the last completed pre-test get? Just the number.” For a presentation, try “Make three slides using the maps and the colors from this project's brand guide.” Reading a completed pre-test and its maps does not use your quota for new analyses.

[Claude guide](https://support.claude.com/en/articles/13837440-use-plugins-in-claude) · [ChatGPT guide](https://help.openai.com/en/articles/20001256-plugins-in-chatgpt) · [Guía en español](https://docs.myunite.ai/es/plugin-unite#instalar-el-plugin-de-unite)

## Connect

The simplest way is to sign in with your Unite account: the app opens a Unite page, you sign in and authorize, and you choose the workspace in the conversation. No key needed.

> [tab] Claude
>
> In claude.ai, on the web or in the app:
>
> > [!TIP]
> >
> > Shortcut: the **Claude** button at the top of this page opens the dialog already filled in with the name and address. Click **Continue** and pick up at step 3.
>
> **1. Open the connectors**
>
> Go to **Settings › Connectors**.
>
> **2. Add the connector**
>
> Click **Add › Add custom connector**. Use the name `Unite` and the MCP server URL `https://mcp.myunite.ai/mcp`, then click **Continue**.
>
> **3. Leave authentication as it came**
>
> Claude detects the sign-in option on its own. Do not fill in a header or a key. Click **Add**.
>
> **4. Connect**
>
> Click **Connect**. The Unite page opens: sign in and click **Autorizar** (Authorize). You choose the workspace in the conversation. You return to Claude with "Connected to Unite".
>
> **5. Use it**
>
> In a conversation, ask, for example: "Use Unite and tell me how much pre-test quota the workspace has." The first time, Claude asks for permission to use the tool.
>
> On Team and Enterprise plans, an Owner adds the connector in **Organization settings › Connectors**. Then each person clicks **Connect** and authorizes with their own account.

> [tab] ChatGPT
>
> **1. Add the server**
>
> Open [Plugins](https://chatgpt.com/plugins) and click **Add › Add custom MCP server**.
>
> **2. Fill in the details**
>
> Use the name `Unite`. Under **Connection**, set **Server URL** to `https://mcp.myunite.ai/mcp`. Under **Authentication**, leave **OAuth**: ChatGPT detects the rest on its own.
>
> **3. Create the plugin**
>
> Check the box that says you understand and want to continue, then click **Create as plugin**.
>
> **4. Authorize**
>
> Click Continue. The Unite page opens: sign in and click **Autorizar** (Authorize). You choose the workspace in the conversation.
>
> **5. Use it**
>
> In a conversation, type `@Unite` and your request.
>
> Your ChatGPT account and workspace policies decide whether you can add MCP servers.

> [tab] Claude Code
>
> **1. Add the server**
>
> In your terminal, outside a Claude Code session:
>
> ```bash theme={null}
> claude mcp add --transport http unite https://mcp.myunite.ai/mcp
> ```
>
> **2. Sign in**
>
> Run `claude mcp login unite` (or, in a Claude Code session, `/mcp` › `unite` › authenticate). The browser opens the Unite page: sign in and click **Autorizar** (Authorize). You choose the workspace in the conversation.
>
> **3. Check**
>
> `claude mcp list` shows `unite … Connected`.
>
> To share the setup with your team, use `--scope project`, which writes the project's `.mcp.json` file.

> [tab] Cursor and others
>
> Clients that cannot open a sign-in page use an API key. See [With an API key](#with-an-api-key).
>
> In Cursor, in `.cursor/mcp.json`:
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "unite": {
>       "url": "https://mcp.myunite.ai/mcp",
>       "headers": {
>         "Authorization": "Bearer ${env:UNITE_API_KEY}"
>       }
>     }
>   }
> }
> ```
>
> Save the file and restart Cursor.
>
> In Claude Code, to use an API key instead of signing in, for example in an automation:
>
> ```bash theme={null}
> claude mcp add --transport http unite https://mcp.myunite.ai/mcp \
>   --header "Authorization: Bearer $UNITE_API_KEY"
> ```

## With your account

One login works for all your workspaces. On the authorization page you only sign in and click **Autorizar** (Authorize). You choose the workspace in the conversation, with two tools: `unite_list_workspaces` shows your workspaces and which one is active, and `unite_select_workspace` changes the active one. For example, ask "use the Brand X workspace".

The agent acts only in the active workspace, with the permissions of your role in it:

| Role in the workspace | What the agent can do |
| - | - |
| Viewer | Check the catalog, the quota, pre-tests and reports. |
| Editor or Administrator | Everything a Viewer can, plus create and delete pre-tests and upload files. Also create and complete brands. |
| Financial | Cannot connect. |

* The connection requests `brands:write` along with the Ad Score permissions. The permission comes with the role: Editors and Administrators get `brands:write` with the rest, with no extra option on the consent screen. Viewers never receive this permission. [Brands](https://docs.myunite.ai/en/brands.md)
* The active workspace is named in every agent result and on the Ad Score card. Check it before creating a pre-test: it uses the quota or credits of the active workspace.
* If you have one workspace, it is active from the start. With several, the agent asks which one to use the first time.
* The choice applies to each connected app. Switching workspace in ChatGPT does not change the one in Claude.
* If you leave the workspace or become Financial, access to it stops on the next call. Unite never switches workspace on its own: the answer is [`workspace_unavailable`](https://docs.myunite.ai/en/errors#workspace_unavailable), and you choose another one.
* In the workspace admin panel, the **Aplicativos conectados** (Connected apps) tab lists your connections and lets you revoke each one. Administrators see and revoke every connection in the workspace. Revocation applies to that workspace only, from the next call, and the app does not come back on its own: only a new authorization in the browser restores it.
* Sign-in works on `https://mcp.myunite.ai/mcp`. The `/mcp/adscore` slice accepts API keys only.

> [!WARNING]
>
> With write access, each pre-test the agent creates uses 1 unit of the workspace quota. With no quota left, it uses 5 credits.

## With an API key

Send the key in the `Authorization` header, as with the API: `Authorization: Bearer <key>`. See [Authentication](https://docs.myunite.ai/en/authentication.md).

The list of tools depends on the key's scopes:

* `adscore:read` shows the read tools;
* `adscore:write` adds creating and deleting pre-tests and uploading files.

With `brands:write`, the connector adds brand tools and uploads. To add the scope to an existing connection, follow [Brands](https://docs.myunite.ai/en/brands.md). A missing, invalid, revoked or expired key gets `401` before any tool runs.

> [!WARNING]
>
> The agent acts with your key. Each new pre-test uses 1 unit of the workspace quota or, with no quota left, 5 credits. Create a key just for the agent, with only the scopes it needs and an expiry.

### Address

| Address | What it serves |
| - | - |
| `https://mcp.myunite.ai/mcp` | Every tool the key or the connection can use. |
| `https://mcp.myunite.ai/mcp/adscore` | Ad Score only. |

The transport is HTTP (Streamable HTTP), with no session.

### In code

> [tab] Anthropic API
>
> The MCP connector of the Anthropic API takes the key in `authorization_token`, without `Bearer`:
>
> ```python theme={null}
> import os
> import anthropic
>
> client = anthropic.Anthropic()
>
> response = client.beta.messages.create(
>     model="claude-sonnet-5-5",
>     max_tokens=2000,
>     betas=["mcp-client-2025-11-20"],
>     mcp_servers=[
>         {
>             "type": "url",
>             "url": "https://mcp.myunite.ai/mcp",
>             "name": "unite",
>             "authorization_token": os.environ["UNITE_API_KEY"],
>         }
>     ],
>     tools=[{"type": "mcp_toolset", "mcp_server_name": "unite"}],
>     messages=[
>         {"role": "user", "content": "How many pre-tests do I have left in my quota?"}
>     ],
> )
> ```

> [tab] OpenAI API
>
> The `mcp` tool of the Responses API takes the key in `authorization`, without `Bearer`. The example skips approval only for the read tools:
>
> ```python theme={null}
> import os
> from openai import OpenAI
>
> client = OpenAI()
>
> response = client.responses.create(
>     model="gpt-6.2-astra",
>     tools=[
>         {
>             "type": "mcp",
>             "server_label": "unite",
>             "server_url": "https://mcp.myunite.ai/mcp",
>             "authorization": os.environ["UNITE_API_KEY"],
>             "require_approval": {
>                 "never": {
>                     "tool_names": [
>                         "adscore_get_catalog",
>                         "adscore_list_pretests",
>                         "adscore_get_pretest",
>                         "adscore_get_pretest_card",
>                         "adscore_get_report",
>                         "unite_get_skill",
>                     ]
>                 }
>             },
>         }
>     ],
>     input="How many pre-tests do I have left in my quota?",
> )
> ```

Cursor and the Anthropic and OpenAI APIs use the API key.

## Tools

| Tool | What it does | Scope |
| - | - | - |
| `adscore_get_catalog` | Channels, OOH formats, platforms and placements, workspace brands and the quota. | `adscore:read` |
| `adscore_list_pretests` | Lists pre-tests, with filters and pagination. | `adscore:read` |
| `adscore_get_pretest` | Status and result of one pre-test. It can wait up to 40 seconds for the analysis to finish. | `adscore:read` |
| `adscore_get_pretest_card` | Shows the Ad Score card again for a `pretestId`, with maps, score, pillars, checks, recommendations and the PDF. `adscore_get_pretest` already shows the card with its result. Free and immediate. | `adscore:read` |
| `adscore_get_report` | Link to the PDF of a completed pre-test. | `adscore:read` |
| `adscore_create_pretest` | Creates a pre-test from a public URL (`mediaUrl`), an `uploadId` or, in ChatGPT, an attached file (`file`). Uses 1 quota unit or, with no quota left, 5 credits. | `adscore:write` |
| `adscore_delete_pretest` | Deletes a completed or failed pre-test. | `adscore:write` |
| `unite_create_upload` | Stores an image or video and returns the `uploadId`. | `adscore:write` or `brands:write` |
| `unite_create_brand` | Creates a workspace brand. | `brands:write` |
| `unite_update_brand` | Completes a brand while preserving saved data. | `brands:write` |
| `unite_get_skill` | Returns a [Unite guide](#unite-guides) in Markdown. Free and immediate. | Any of `adscore:read`, `adscore:write` or `brands:write` |
| `unite_list_workspaces` | Lists the workspaces where you can use Unite, with the active one, your role, the quota and the credits of each. Free and immediate. | Any of `adscore:read`, `adscore:write` or `brands:write` |
| `unite_select_workspace` | Chooses which workspace the next calls act in and remembers the choice. Takes the `workspaceId` from `unite_list_workspaces`. Free and immediate. | Any of `adscore:read`, `adscore:write` or `brands:write` |

Names start with the product: `adscore_` for Ad Score and `unite_` for what every product shares.

## Unite guides

Unite's skills are guides, in Markdown, for doing a task with the Unite tools. The agent reads each one with `unite_get_skill`.

| Skill | What it is for |
| - | - |
| `ad-score` | Run, read and present Ad Score pre-tests. |
| `brand-guidelines` | Save the workspace brand. |

The `ad-score` skill also has four references:

* `references/presenting-results.md`: how to present a result, in the chat, in a report or in slides.
* `references/reading-results.md`: what each part of the result means.
* `references/channels.md`: what each channel needs and what its checks look at.
* `references/comparing-pretests.md`: how to compare creatives, versions or a set of pre-tests.

How to use them:

* Pass the skill in `name`. Without `file`, the answer carries `SKILL.md` and the list of the skill's files. With `file`, it carries that file, such as `references/presenting-results.md`.
* Each answer carries the skill version and the file's `digest`.
* Reading a guide is free and immediate, and works with any scope of the server.
* When a pre-test is completed, the `adscore_get_pretest` result carries a line pointing to the presentation guide: the `references/presenting-results.md` file of the `ad-score` skill.
* The [Unite plugin](#install-the-unite-plugin) 1.3.0 ships the same skills, as `unite:ad-score` and `unite:brand-guidelines`.

## How the agent works

* **Media:**
  * In ChatGPT, a file attached in the chat goes straight to `adscore_create_pretest` as `file`, with the same limits as `mediaUrl`. ChatGPT fills in that field itself.
  * In other chat clients, the agent cannot pass an attached file inside a tool call.
  * Pass a public URL of the creative in `mediaUrl`. Unite downloads the file with the same rules as [uploading from a URL](https://docs.myunite.ai/en/uploads.md#upload-from-a-url).
  * Through MCP, the download gets up to 45 seconds, to fit the clients' request timeout. For large files or slow servers, use the API's [upload from a URL](https://docs.myunite.ai/en/uploads.md#upload-from-a-url), which waits up to 120 seconds.
* **Time:**
  * The analysis takes a few minutes. `adscore_create_pretest` answers at once, with status `queued` and `pollAfterSeconds`.
  * Then `adscore_get_pretest` with `waitSeconds` (up to 40) waits on the server and answers as soon as the analysis finishes.
* **Retrying without being charged again:**
  * Without `idempotencyKey`, the idempotency key comes from the arguments themselves. The same call repeated, for example after a timeout, returns the same pre-test and is not charged again.
  * If `mediaUrl` is a signed link that changes on every attempt, the derived key changes with it and the retry creates another pre-test. In that case, send your own `idempotencyKey` and retry with it.
  * To analyze the same creative once more, send a new `idempotencyKey`.
  * Reusing the same `idempotencyKey` with a different `mediaUrl` returns the original pre-test.
  * After a pre-test is deleted, the same call answers [`idempotency_key_retired`](https://docs.myunite.ai/en/errors#idempotency_key_retired). Send a new `idempotencyKey` to analyze the creative again.
  * See [Idempotency](https://docs.myunite.ai/en/idempotency.md).
* **Result:**
  * By default, `adscore_get_pretest` returns the first 3 findings and recommendations, with each list's total in `truncated`.
  * With `detail: "full"`, it returns all findings and recommendations with the available [supporting evidence](https://docs.myunite.ai/en/results.md#full-detail). By default, summary requests a heatmap preview and full detail requests all available map previews. Set `mapImages: "none"` to request data and map URLs without previews.
  * To get the PDF directly, call `adscore_get_report` on a completed pre-test. If the report is generating, wait `pollAfterSeconds` and call again for the download URL.

## Limits and errors

* **Limits:**
  * Each tool call counts toward the per-minute limit of the key or the connection, with the same quotas as the API: read for the read tools, write for the others.
  * Listing the tools does not count.
  * See [Rate limits](https://docs.myunite.ai/en/rate-limits.md).
* **Tool errors:**
  * A tool that fails answers with `isError: true`.
  * The text carries the same error JSON as the API: `code`, `message`, `requestId`, `docUrl` and, when there is one, `param`.
  * For the per-minute limit and the cap on running pre-tests, the error also carries `retryAfterSeconds`.
  * Code against `code`. See [Errors](https://docs.myunite.ai/en/errors.md).
* **Support:** when you write to [support@myunite.ai](mailto:support@myunite.ai), include the `requestId`.


## Related topics

- [Changelog](https://docs.myunite.ai/en/changelog.md)
- [Errors](https://docs.myunite.ai/en/errors.md)
- [File uploads](https://docs.myunite.ai/en/uploads.md)
- [Authentication](https://docs.myunite.ai/en/authentication.md)
- [First pre-test](https://docs.myunite.ai/en/quickstart.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.