> ## 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 para agentes de IA

> Conecte o Claude, o ChatGPT e o Claude Code à Unite com a sua conta, ou qualquer agente com uma chave de API.

O servidor MCP da Unite deixa um agente de IA usar o Ad Score:

* consultar o catálogo e a cota;
* enviar uma peça;
* criar e acompanhar pré-testes;
* ler o resultado e baixar o PDF.

Ele segue as mesmas permissões, os mesmos limites e os mesmos códigos de erro da API.

Para obter o conector e as skills da Unite juntos, [instale o plugin da Unite](#instalar-o-plugin-da-unite).

> [card] [Claude](https://claude.ai/customize/connectors?modal=add-custom-connector\&connectorName=Unite\&connectorUrl=https%3A%2F%2Fmcp.myunite.ai%2Fmcp)
>
> Abre o Claude com o conector da Unite já preenchido. Clique em Continuar, Adicionar e Vincular.

> [card] [ChatGPT](https://chatgpt.com/plugins)
>
> Abre os Plugins do ChatGPT. Clique em Adicionar › Adicionar servidor MCP personalizado e cole o endereço.

> [card] [Claude Code](#conectar)
>
> Um comando no terminal e o login no navegador.

Endereço para colar:

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

Na página da Unite que abrir, entre com o seu login de sempre e clique em **Autorizar**. O workspace você escolhe na conversa.

Depois de conectar, [faça um teste no Claude](https://claude.ai/new?q=Use%20a%20Unite%20e%20me%20diga%20quanto%20de%20cota%20de%20pr%C3%A9-teste%20o%20workspace%20tem.): a conversa abre com o pedido escrito, e você só envia.

## Instalar o plugin da Unite

O plugin, na versão 1.3.0, instala o conector e duas skills juntos. O conector busca os resultados. A skill `unite:ad-score` ajuda a rodar, ler e apresentar os pré-testes no formato que você pedir. A skill `unite:brand-guidelines` ajuda a salvar a marca do workspace. São os mesmos [guias da Unite](#guias-da-unite) que o conector entrega.

* **Claude.** Em um plano pago com instalação permitida pelo workspace, baixe o [plugin para Claude](https://myunite.ai/home/plugins/unite.plugin). Abra **Personalizar › Plugins**, escolha a opção de carregar um plugin personalizado e selecione `unite.plugin`.
* **ChatGPT na web.** Baixe o [plugin para ChatGPT](https://myunite.ai/home/plugins/unite-chatgpt.zip). Um administrador com permissão de upload escolhe o workspace no **Admin console**, abre **Plugins › Add › Upload plugin** e envia o ZIP. Se o administrador escolher **Available**, cada pessoa abre o plugin e clica em **Install plugin**. Com **Installed**, ele já fica instalado para as pessoas selecionadas.

Depois de instalar no seu aplicativo, abra a conexão com a Unite e entre na sua conta. O workspace dos pré-testes você escolhe na conversa.

Se o workspace do ChatGPT já usa um conector personalizado da Unite e uma opção nova ainda não aparece, o administrador pode atualizar as ferramentas nas configurações do aplicativo e publicar as alterações revisadas. [Como atualizar uma conexão existente no ChatGPT](https://help.openai.com/en/articles/12584461-connecting-custom-mcp-servers-in-chatgpt)

Experimente pedir “Qual foi a nota do último pré-teste concluído? Só o número.” Para uma apresentação, peça “Use os mapas e as cores do guia de marca deste projeto para montar três slides.” Consultar um pré-teste concluído e seus mapas não consome a cota de novas análises.

[Guia do Claude](https://support.claude.com/en/articles/13837440-use-plugins-in-claude) · [Guia do ChatGPT](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)

## Conectar

O jeito mais simples é entrar com a sua conta da Unite: o aplicativo abre uma página da Unite, você entra e autoriza, e o workspace você escolhe na conversa. Não precisa de chave.

> [tab] Claude
>
> No claude.ai, na web ou no app:
>
> > [!TIP]
> >
> > Atalho: o botão **Claude** no topo desta página abre a janela já preenchida com o nome e o endereço. Clique em **Continuar** e siga do passo 3.
>
> **1. Abra os conectores**
>
> Vá em **Configurações › Conectores** (Settings › Connectors).
>
> **2. Adicione o conector**
>
> Clique em **Adicionar › Adicionar conector personalizado** (Add › Add custom connector). Use o nome `Unite`, a URL do servidor MCP `https://mcp.myunite.ai/mcp` e clique em **Continuar**.
>
> **3. Deixe a autenticação como veio**
>
> O Claude detecta sozinho **Entrar agora** e **Usar a identidade publicada do Claude**. Não preencha cabeçalho nem chave. Clique em **Adicionar** (Add).
>
> **4. Vincule**
>
> Clique em **Vincular** (Connect). A página da Unite abre: entre e clique em **Autorizar**. O workspace você escolhe na conversa. Você volta ao Claude com "Conectado à Unite".
>
> **5. Use**
>
> Numa conversa, peça, por exemplo: "Use a Unite e me diga quanto de cota de pré-teste o workspace tem." Na primeira vez, o Claude pede permissão para usar a ferramenta.
>
> Nos planos Team e Enterprise, um Owner adiciona o conector em **Configurações da organização › Conectores** (Organization settings › Connectors). Depois, cada pessoa clica em **Vincular** e autoriza com a própria conta.

> [tab] ChatGPT
>
> **1. Adicione o servidor**
>
> Abra [Plugins](https://chatgpt.com/plugins) e clique em **Adicionar › Adicionar servidor MCP personalizado** (Add › Add custom MCP server).
>
> **2. Preencha os dados**
>
> Use o nome `Unite`. Em **Conexão** (Connection), coloque em **URL do servidor** `https://mcp.myunite.ai/mcp`. Em **Autenticação**, deixe **OAuth**: o ChatGPT detecta sozinho o resto.
>
> **3. Crie o plugin**
>
> Marque **Entendo e quero continuar** e clique em **Criar como plugin** (Create as plugin).
>
> **4. Autorize**
>
> Clique em **Continuar em Unite**. A página da Unite abre: entre e clique em **Autorizar**. O workspace você escolhe na conversa.
>
> **5. Use**
>
> Numa conversa, digite `@Unite` e o pedido.
>
> As regras da sua conta e do seu workspace no ChatGPT decidem se você pode adicionar servidores MCP.

> [tab] Claude Code
>
> **1. Adicione o servidor**
>
> No terminal, fora de uma sessão do Claude Code:
>
> ```bash theme={null}
> claude mcp add --transport http unite https://mcp.myunite.ai/mcp
> ```
>
> **2. Entre**
>
> Rode `claude mcp login unite` (ou, numa sessão do Claude Code, `/mcp` › `unite` › autenticar). O navegador abre a página da Unite: entre e clique em **Autorizar**. O workspace você escolhe na conversa.
>
> **3. Confira**
>
> `claude mcp list` mostra `unite … Connected`.
>
> Para dividir a configuração com o time, use `--scope project`, que grava o arquivo `.mcp.json` do projeto.

> [tab] Cursor e outros
>
> Clientes que não abrem página de login usam uma chave de API. Veja [Com uma chave de API](#com-uma-chave-de-api).
>
> No Cursor, em `.cursor/mcp.json`:
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "unite": {
>       "url": "https://mcp.myunite.ai/mcp",
>       "headers": {
>         "Authorization": "Bearer ${env:UNITE_API_KEY}"
>       }
>     }
>   }
> }
> ```
>
> Salve o arquivo e reinicie o Cursor.
>
> No Claude Code, para usar uma chave de API no lugar do login, por exemplo numa automação:
>
> ```bash theme={null}
> claude mcp add --transport http unite https://mcp.myunite.ai/mcp \
>   --header "Authorization: Bearer $UNITE_API_KEY"
> ```

## Com a sua conta

Um login vale para todos os seus workspaces. Na página de autorização, você só entra e clica em **Autorizar**. O workspace você escolhe na conversa, com duas ferramentas: `unite_list_workspaces` mostra os seus workspaces e qual está ativo, e `unite_select_workspace` troca o ativo. Por exemplo, peça "usa o workspace Marca X".

O agente age só no workspace ativo e com as permissões do seu papel nele:

| Papel no workspace | O que o agente pode fazer |
| - | - |
| Visualizador | Consultar o catálogo, a cota, os pré-testes e os relatórios. |
| Editor ou Administrador | Tudo o que o Visualizador faz, mais criar e excluir pré-testes e enviar arquivos. Também cria e completa marcas. |
| Financeiro | Não conecta. |

* A conexão pede `brands:write` junto com as permissões do Ad Score. A permissão vem com o papel: Editor e Administrador recebem `brands:write` junto com o resto, sem opção extra na autorização. O Visualizador nunca recebe essa permissão. [Marcas](https://docs.myunite.ai/brands.md)
* O workspace ativo aparece em toda resposta do agente e no cartão do Ad Score. Confira antes de criar um pré-teste: ele usa a cota ou os créditos do workspace ativo.
* Se você tem um só workspace, ele já vem ativo. Com vários, o agente pergunta qual usar na primeira vez.
* A escolha vale para cada aplicativo conectado. Trocar de workspace no ChatGPT não muda o do Claude.
* Se você sair do workspace ou passar a Financeiro, o acesso a ele cai na chamada seguinte. A Unite não troca de workspace sozinha: a resposta é [`workspace_unavailable`](https://docs.myunite.ai/errors#workspace_unavailable), e você escolhe outro.
* No painel do workspace, a aba **Aplicativos conectados** mostra as suas conexões e deixa revogar cada uma. O administrador vê e revoga as de todo o workspace. A revogação vale só para aquele workspace, na chamada seguinte, e o aplicativo não volta sozinho: só uma nova autorização no navegador libera.
* O login vale no endereço `https://mcp.myunite.ai/mcp`. O recorte `/mcp/adscore` aceita só chave de API.

> [!WARNING]
>
> Com escrita, cada pré-teste que o agente cria usa 1 unidade da cota do workspace. Sem cota, usa 5 créditos.

## Com uma chave de API

Envie a chave no cabeçalho `Authorization`, como na API: `Authorization: Bearer <chave>`. Veja [Autenticação](https://docs.myunite.ai/authentication.md).

A lista de ferramentas depende das permissões da chave:

* `adscore:read` mostra as ferramentas de leitura;
* `adscore:write` acrescenta criar e excluir pré-testes e enviar arquivos.

Com `brands:write`, o conector inclui as ferramentas de marca e de upload. Para conceder o escopo a uma conexão existente, veja [Marcas](https://docs.myunite.ai/brands.md). Uma chave ausente, inválida, revogada ou vencida recebe `401` antes de qualquer ferramenta.

> [!WARNING]
>
> O agente age com a sua chave. Cada pré-teste novo usa 1 unidade da cota do workspace ou, sem cota, 5 créditos. Crie uma chave só para o agente, com as permissões que ele precisa e com validade.

### Endereço

| Endereço | O que traz |
| - | - |
| `https://mcp.myunite.ai/mcp` | Todas as ferramentas que a chave ou a conexão pode usar. |
| `https://mcp.myunite.ai/mcp/adscore` | Só o Ad Score. |

O transporte é HTTP (Streamable HTTP), sem sessão.

### Em código

> [tab] API da Anthropic
>
> O conector MCP da API da Anthropic recebe a chave em `authorization_token`, sem o `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": "Quantos pré-testes ainda tenho na cota?"}
>     ],
> )
> ```

> [tab] API da OpenAI
>
> A ferramenta `mcp` da Responses API recebe a chave em `authorization`, sem o `Bearer`. O exemplo dispensa a aprovação só nas ferramentas de leitura:
>
> ```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="Quantos pré-testes ainda tenho na cota?",
> )
> ```

O Cursor e as APIs da Anthropic e da OpenAI usam a chave de API.

## Ferramentas

| Ferramenta | O que faz | Permissão |
| - | - | - |
| `adscore_get_catalog` | Canais, formatos de OOH, plataformas e posições, marcas do workspace e a cota. | `adscore:read` |
| `adscore_list_pretests` | Lista os pré-testes, com filtros e paginação. | `adscore:read` |
| `adscore_get_pretest` | Status e resultado de um pré-teste. Pode esperar até 40 segundos pelo fim da análise. | `adscore:read` |
| `adscore_get_pretest_card` | Mostra de novo o cartão do Ad Score de um `pretestId`, com mapas, nota, pilares, verificações, recomendações e o PDF. `adscore_get_pretest` já mostra o cartão junto com o resultado. Grátis e imediato. | `adscore:read` |
| `adscore_get_report` | Link do PDF de um pré-teste concluído. | `adscore:read` |
| `adscore_create_pretest` | Cria um pré-teste a partir de uma URL pública (`mediaUrl`), de um `uploadId` ou, no ChatGPT, de um arquivo anexado (`file`). Usa 1 unidade da cota ou, sem cota, 5 créditos. | `adscore:write` |
| `adscore_delete_pretest` | Exclui um pré-teste concluído ou que falhou. | `adscore:write` |
| `unite_create_upload` | Guarda uma imagem ou um vídeo e devolve o `uploadId`. | `adscore:write` ou `brands:write` |
| `unite_create_brand` | Cria uma marca no workspace. | `brands:write` |
| `unite_update_brand` | Completa uma marca preservando os dados salvos. | `brands:write` |
| `unite_get_skill` | Devolve um [guia da Unite](#guias-da-unite) em Markdown. Grátis e imediato. | Qualquer uma: `adscore:read`, `adscore:write` ou `brands:write` |
| `unite_list_workspaces` | Lista os workspaces em que você pode usar a Unite, com o ativo, o papel, a cota e os créditos de cada um. Grátis e imediato. | Qualquer uma: `adscore:read`, `adscore:write` ou `brands:write` |
| `unite_select_workspace` | Escolhe em qual workspace as próximas chamadas agem e guarda a escolha. Recebe o `workspaceId` de `unite_list_workspaces`. Grátis e imediato. | Qualquer uma: `adscore:read`, `adscore:write` ou `brands:write` |

Os nomes começam pelo produto: `adscore_` para o Ad Score e `unite_` para o que vale para todos os produtos.

## Guias da Unite

As skills da Unite são guias em Markdown de como fazer uma tarefa com as ferramentas da Unite. O agente lê cada uma com `unite_get_skill`.

| Skill | Para que serve |
| - | - |
| `ad-score` | Rodar, ler e apresentar pré-testes do Ad Score. |
| `brand-guidelines` | Salvar a marca do workspace. |

A skill `ad-score` tem também quatro referências:

* `references/presenting-results.md`: como apresentar um resultado, na conversa, num relatório ou em slides.
* `references/reading-results.md`: o que cada parte do resultado significa.
* `references/channels.md`: o que cada canal pede e o que as verificações dele avaliam.
* `references/comparing-pretests.md`: como comparar peças, versões ou vários pré-testes.

Como usar:

* Passe a skill em `name`. Sem `file`, a resposta traz o `SKILL.md` e a lista dos arquivos da skill. Com `file`, traz aquele arquivo, por exemplo `references/presenting-results.md`.
* Cada resposta traz a versão da skill e o `digest` do arquivo.
* Ler um guia é grátis e imediato, e funciona com qualquer permissão do servidor.
* Quando um pré-teste está concluído, o resultado de `adscore_get_pretest` traz uma linha que aponta o guia de apresentação: o arquivo `references/presenting-results.md` da skill `ad-score`.
* O [plugin da Unite](#instalar-o-plugin-da-unite) 1.3.0 traz as mesmas skills, como `unite:ad-score` e `unite:brand-guidelines`.

## Como o agente trabalha

* **Mídia:**
  * No ChatGPT, um arquivo anexado na conversa vai direto para `adscore_create_pretest` no campo `file`, com os mesmos limites da `mediaUrl`. O próprio ChatGPT preenche esse campo.
  * Em outros clientes de chat, o agente não consegue mandar um arquivo anexado dentro de uma ferramenta.
  * Passe uma URL pública da peça em `mediaUrl`. A Unite baixa o arquivo com as mesmas regras do [envio por URL](https://docs.myunite.ai/uploads.md#enviar-por-url).
  * Pelo MCP, o download tem até 45 segundos, para caber no tempo de espera dos clientes. Para arquivos grandes ou servidores lentos, use o [envio por URL](https://docs.myunite.ai/uploads.md#enviar-por-url) da API, que espera até 120 segundos.
* **Tempo:**
  * A análise leva alguns minutos. `adscore_create_pretest` responde na hora, com o status `queued` e `pollAfterSeconds`.
  * Em seguida, `adscore_get_pretest` com `waitSeconds` (até 40) espera no servidor e responde assim que a análise termina.
* **Repetição sem cobrança:**
  * Sem `idempotencyKey`, a chave de idempotência vem dos próprios argumentos. A mesma chamada repetida, por exemplo depois de um tempo esgotado, devolve o mesmo pré-teste e não cobra de novo.
  * Se a `mediaUrl` for um link assinado que muda a cada tentativa, a chave derivada muda junto e a repetição cria outro pré-teste. Nesse caso, envie uma `idempotencyKey` sua e repita com ela.
  * Para analisar a mesma peça outra vez, envie uma `idempotencyKey` nova.
  * Reusar a mesma `idempotencyKey` com uma `mediaUrl` diferente devolve o pré-teste original.
  * Depois que um pré-teste é excluído, a mesma chamada responde [`idempotency_key_retired`](https://docs.myunite.ai/errors#idempotency_key_retired). Envie uma `idempotencyKey` nova para analisar a peça outra vez.
  * Veja [Idempotência](https://docs.myunite.ai/idempotency.md).
* **Resultado:**
  * `adscore_get_pretest` traz por padrão os 3 primeiros achados e recomendações, com o total de cada lista em `truncated`.
  * Com `detail: "full"`, devolve todos os achados e recomendações com as [evidências disponíveis](https://docs.myunite.ai/results.md#detalhe-completo). Por padrão, o resumo solicita uma prévia do mapa de calor e o detalhe completo solicita prévias de todos os mapas disponíveis. Use `mapImages: "none"` para receber dados e URLs sem prévias.
  * Para obter o PDF diretamente, chame `adscore_get_report` em um pré-teste concluído. Se estiver em geração, aguarde `pollAfterSeconds` e repita a consulta para receber a URL de download.

## Limites e erros

* **Limites:**
  * Cada chamada de ferramenta conta no limite por minuto da chave ou da conexão, com as mesmas cotas da API: leitura nas ferramentas de leitura e escrita nas outras.
  * Listar as ferramentas não conta.
  * Veja [Limites de uso](https://docs.myunite.ai/rate-limits.md).
* **Erro de ferramenta:**
  * Uma ferramenta que falha responde com `isError: true`.
  * O texto traz o mesmo JSON de erro da API: `code`, `message`, `requestId`, `docUrl` e, quando há, `param`.
  * No limite por minuto e no teto de pré-testes em andamento, o erro traz também `retryAfterSeconds`.
  * Programe pelo `code`. Veja [Erros](https://docs.myunite.ai/errors.md).
* **Suporte:** ao escrever para [support@myunite.ai](mailto:support@myunite.ai), informe o `requestId`.


## Related topics

- [Changelog](https://docs.myunite.ai/changelog.md)
- [Limites de uso](https://docs.myunite.ai/rate-limits.md)
- [Erros](https://docs.myunite.ai/errors.md)
- [Envio de arquivos](https://docs.myunite.ai/uploads.md)
- [Pré-teste de e-mail](https://docs.myunite.ai/pretests/email.md)


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