# Documentação do servidor MCP do Chattee

O servidor MCP do Chattee é um servidor remoto do Model Context Protocol que permite a assistentes de IA como o Claude Code, o Claude.ai, o Cursor, o Codex e o ChatGPT criar, alterar, implementar e publicar apps web completas no Chattee. Esta página mostra como ligar cada cliente, como funcionam a autenticação e as permissões, o que fazem as 35 ferramentas e os limites com que te vais deparar.

## O que é o servidor MCP do Chattee?

O servidor MCP do Chattee permite que o assistente de IA que já usas construa apps web completas no [Chattee](/pt): cria um projeto a partir da tua descrição, transmite-te o plano para aprovares, acompanha a construção e publica a app em Ao vivo. É um único endpoint remoto, autenticado por OAuth ou por um token de acesso pessoal.

Fala o Model Context Protocol (revisões 2025-11-25 e 2026-07-28) por Streamable HTTP, num único URL:

```text
https://chattee.ai/mcp/connect
```

Através dele, o teu assistente pode criar um projeto a partir de uma descrição, transmitir-te o plano que o Chattee propõe e levar-lhe a tua resposta, acompanhar a construção, entregar-te a pré-visualização do Rascunho, publicar em Ao vivo, começar projetos a partir de modelos ou exportá-los como modelos, ler e escrever ficheiros, gerir variáveis de ambiente e recursos geridos, ler a base de dados e consultar os teus créditos. O Chattee constrói apps web completas: um front-end React, um back-end Node, uma base de dados Postgres gerida, autenticação, armazenamento de ficheiros e e-mail, implementados e alojados em chattee.ai.

A única regra que molda tudo: **os planos e as decisões sobre dinheiro ficam contigo.** Cada plano é-te mostrado completo e só tu o aprovas; uma execução que atinge o orçamento fica em pausa, e o seu limite sobe só até um total que tu indiques. Os créditos compram-se no builder, nunca pelo teu assistente.

## O que posso pedir ao meu assistente para fazer com o Chattee?

Pede com as tuas palavras, como explicarias o projeto a um programador: o teu assistente transforma o pedido em chamadas às ferramentas do Chattee e mostra-te o que volta. Uma app nova passa por um plano que aprovas; uma pequena alteração pode entrar diretamente. A tabela mostra pedidos reais e as ferramentas que usaram.

| Pedes | O que acontece | Ferramentas chamadas |
|---|---|---|
| *Faz-me um site de uma página para a minha padaria, «Sunrise Bakery»: um destaque com o nome e uma frase curta, três cartões para o nosso pão, os bolos e o café, o horário de funcionamento e uma secção de contacto com a nossa morada (12 Baker Street, Springfield). Sem início de sessão, sem área de administração. Publica-o quando estiver pronto.* | O Chattee planeia um site de uma página sem back-end e faz duas perguntas sobre o aspeto; depois do teu sim, constrói a página e publica-a. | `create_project`, `wait_for_run`, `answer_question`, `approve_plan`, `publish_project`, `get_release_status` |
| *Constrói um portal de alunos para o meu centro de explicações, o Brightpath Tutoring. Os alunos iniciam sessão e veem as suas próprias notas e assiduidade, e carregam lá os seus trabalhos. Quando um aluno entrega um trabalho, quero receber um e-mail sobre isso. Publica-o quando funcionar.* | O Chattee pergunta como é que os alunos obtêm contas e que aspeto deve ter o portal, planeia uma app full-stack (início de sessão, base de dados, armazenamento de ficheiros, e-mail) para o teu sim, constrói-a, continuando uma vez depois do limite de tempo da execução, e publica-a. | `create_project`, `wait_for_run`, `answer_question`, `approve_plan`, `set_env_vars`, `get_project`, `get_run_logs`, `list_resources`, `get_release_status`, `continue_run`, `list_env_vars`, `publish_project` |
| *Faz-me uma app para o nosso clube desportivo, o TSV Grünwald. Os sócios registam-se e iniciam sessão, veem os horários dos treinos e os próximos eventos e podem inscrever-se num evento; recebem uma confirmação por e-mail. A direção carrega documentos, como atas de reuniões, que todos os sócios podem ler. Publica a app quando estiver pronta.* | O Chattee pergunta pelo aspeto e pela cor do clube, planeia a app dos sócios (início de sessão, base de dados, armazenamento de ficheiros, e-mail) para o teu sim, constrói-a, continuando uma vez depois do limite de tempo da execução, e publica-a. | `create_project`, `wait_for_run`, `answer_question`, `approve_plan`, `continue_run`, `publish_project`, `get_release_status` |
| *Porque é que a última implementação falhou?* | O teu assistente lê o registo de implementação e explica o erro. | `get_run_logs` (`source`) |
| *Muda o título da página inicial para «Fresco todas as manhãs».* | Uma alteração pequena e direta, sem plano; os créditos são gastos de imediato. | `send_message` (`mode`), `wait_for_run` |
| *Quantas pessoas se registaram em Ao vivo?* | Uma consulta só de leitura à base de dados de Ao vivo; as leituras em Ao vivo ficam registadas. | `query_database` (`env`, `sql`) |
| *Volta a pôr em Ao vivo a versão de ontem.* | O teu assistente encontra a versão no histórico e restaura-a em Ao vivo. | `get_release_status`, `publish_project` (`restore_release_uid`) |
| *Guarda este projeto como modelo.* | Um modelo privado com a sua própria base de dados vazia, a partir do qual podes começar projetos novos. | `export_project_as_template` |

As três primeiras linhas são execuções reais do benchmark MCP do Chattee: o pedido tal como o utilizador simulado o escreveu (traduzido, porque os testes correram em inglês e em alemão) e as ferramentas que o assistente chamou, pela ordem em que as chamou pela primeira vez. As restantes são pedidos isolados.

## Requisitos

Precisas de três coisas: uma conta Chattee, um cliente MCP que fale Streamable HTTP e uma forma de iniciar sessão. Os clientes alojados só precisam de iniciar sessão com OAuth; os outros enviam um token de acesso pessoal num cabeçalho. A chave API da tua conta é recusada de propósito, porque não tem permissões delimitadas nem pode ser revogada.

- Uma conta Chattee ([começa grátis](/pt/get-started?plan=free&source=docs_mcp)). O plano gratuito inclui créditos.
- Um cliente MCP: Claude Code, Claude.ai ou Claude Desktop, Cursor, Codex CLI, ChatGPT ou o teu próprio agente com o Claude Agent SDK.
- Ou um **token de acesso pessoal** (criado na [página Assistentes de IA](/app/ai-assistants) do builder), ou um cliente que inicie sessão por **OAuth**. A chave API da tua conta não funciona aqui.

## Como adiciono o servidor MCP do Chattee ao Claude Code?

O Claude Code adiciona o servidor MCP do Chattee com um comando e inicia sessão por OAuth, sem colar nenhum token. Adiciona-o para o teu utilizador, para que esteja em todos os projetos; uma equipa que partilha um repositório pode antes fazer commit de um `.mcp.json`, com o token de cada pessoa lido de uma variável de ambiente.

Adiciona o servidor uma vez e depois inicia sessão:

```bash
claude mcp add --transport http chattee --scope user https://chattee.ai/mcp/connect
```

`--scope user` adiciona o Chattee para o teu utilizador, para estar em todos os projetos e não só na pasta atual (o âmbito predefinido do Claude Code). Inicia sessão a partir da shell:

```bash
claude mcp login chattee
```

Dentro do Claude Code, `/mcp` faz o mesmo: escolhe lá o Chattee. Em qualquer dos casos, o Claude Code abre a página de consentimento do Chattee, tu aprovas e as ferramentas aparecem como `mcp__chattee__<tool>`. Para usar um token de acesso pessoal em vez de OAuth, passa-o como cabeçalho:

```bash
claude mcp add --transport http chattee --scope user https://chattee.ai/mcp/connect --header "Authorization: Bearer chattee_pat_…"
```

Para uma configuração ao nível do projeto que uma equipa possa partilhar, põe isto num `.mcp.json` na raiz do repositório. O ficheiro não contém nenhum token: o Claude Code substitui `${CHATTEE_PAT}` pela variável de ambiente `CHATTEE_PAT`, por isso cada pessoa da equipa usa o seu próprio token de acesso pessoal e o ficheiro pode ir para o repositório tal como está:

```json
{
  "mcpServers": {
    "chattee": {
      "type": "http",
      "url": "https://chattee.ai/mcp/connect",
      "headers": {
        "Authorization": "Bearer ${CHATTEE_PAT}"
      }
    }
  }
}
```

Define a variável antes de abrires o Claude Code, por exemplo no perfil da tua shell (`~/.zshrc` ou `~/.bashrc`): `export CHATTEE_PAT=chattee_pat_…`. Nunca escrevas o próprio token no `.mcp.json` e nunca o ponhas em nenhum commit.

Depois pede ao Claude Code, por exemplo: *«Constrói no Chattee uma página de reservas para o meu estúdio de ioga e mostra-me o plano antes de o aprovares.»*

## Como adiciono o Chattee como conector personalizado no Claude.ai e no Claude Desktop?

O Claude.ai, o Claude Desktop e as apps móveis do Claude ligam-se ao Chattee como conector personalizado: colas o URL do servidor uma vez, inicias sessão no Chattee e aprovas as permissões. A ligação usa OAuth 2.1, funciona em todos os planos do Claude e aparece depois em todas as conversas em que ativares o conector.

Os conectores personalizados estão disponíveis em todos os planos (o plano gratuito permite um conector personalizado). Os menus aparecem aqui com os nomes da interface em inglês:

1. Abre **[Customize → Connectors](https://claude.ai/customize/connectors)** (proprietários de Team e Enterprise: **Organization settings → Connectors**, depois **Add → Custom → Web**).
2. Clica em **+**, escolhe **Add custom connector**, cola `https://chattee.ai/mcp/connect` como URL e clica em **Add**.
3. Liga o conector: o Claude abre a página de consentimento do Chattee. Inicia sessão, revê as permissões e aprova.

O Chattee aparece então como um conector que podes ativar em cada conversa, na web, no Claude Desktop e nas apps móveis. Não colas nenhum token no Claude.

## Como adiciono o servidor MCP do Chattee ao Cursor?

O Cursor instala o servidor MCP do Chattee com um clique, ou com algumas linhas no `mcp.json`, e depois inicia sessão por OAuth na página de consentimento do Chattee. Como o Cursor ignora os cabeçalhos configurados assim que um servidor oferece OAuth, iniciar sessão é a única forma de autenticação; um token no ficheiro não serve de nada.

[Adicionar ao Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=chattee&config=eyJ1cmwiOiJodHRwczovL2NoYXR0ZWUuYWkvbWNwL2Nvbm5lY3QifQ==)

Ou adiciona tu o servidor a `~/.cursor/mcp.json` (ou ao `.cursor/mcp.json` do projeto):

```json
{
  "mcpServers": {
    "chattee": {
      "url": "https://chattee.ai/mcp/connect"
    }
  }
}
```

O Cursor deteta que o servidor oferece OAuth e pede-te para iniciares sessão; aprova na página de consentimento do Chattee.

## Como adiciono o servidor MCP do Chattee ao Codex CLI?

O Codex CLI liga-se ao Chattee com um token de acesso pessoal que lê de uma variável de ambiente, por isso o token nunca fica num ficheiro de configuração. Adiciona o servidor com um comando ou com três linhas de TOML, e mantém a espera predefinida: o Codex termina qualquer chamada de ferramenta ao fim de 60 segundos.

Põe um token de acesso pessoal na variável de ambiente `CHATTEE_PAT` e depois adiciona o servidor:

```bash
codex mcp add chattee --url https://chattee.ai/mcp/connect --bearer-token-env-var CHATTEE_PAT
```

Ou escreve o mesmo em `~/.codex/config.toml`:

```toml
[mcp_servers.chattee]
url = "https://chattee.ai/mcp/connect"
bearer_token_env_var = "CHATTEE_PAT"
```

O Codex termina uma chamada de ferramenta ao fim de 60 segundos, por isso mantém a espera predefinida de 45 segundos do `wait_for_run`; a ferramenta responde antes disso e o Codex simplesmente volta a chamá-la.

## Como ligo o servidor MCP do Chattee ao ChatGPT?

O ChatGPT liga servidores MCP no Developer mode, na página a que agora chama Plugins (antes dizia conectores), nos planos pagos da OpenAI e só na web. O Chattee liga-se apenas por OAuth: colas o URL do servidor, aprovas na página de consentimento do Chattee e depois escolhes o Chattee numa conversa.

A OpenAI oferece o Developer mode nos planos pagos (Plus, Pro, Business, Enterprise e Edu) e só na web; num espaço de trabalho Business, Enterprise ou Edu, pode ser preciso que um administrador o autorize primeiro. Os menus aparecem aqui com os nomes da interface em inglês:

1. Abre **Settings → Security and login** e ativa o **Developer mode**.
2. Vai a **[ChatGPT Plugins](https://chatgpt.com/plugins)**, clica em **+**, escreve um nome (Chattee) e uma breve descrição e cola `https://chattee.ai/mcp/connect` como URL do servidor da ligação. Cria-a.
3. O ChatGPT envia-te para a página de consentimento do Chattee; inicia sessão e aprova.
4. Numa conversa nova, escolhe **Developer mode** no menu **+** e seleciona o Chattee.

O ChatGPT não aceita tokens de acesso pessoal, e não faz mal: o fluxo OAuth concede as mesmas permissões, e revogas a ligação no Chattee, na [página Assistentes de IA](/app/ai-assistants).

## Como uso o servidor MCP do Chattee a partir do Claude Agent SDK?

Um agente que constróis com o Claude Agent SDK chega ao Chattee pelo mesmo servidor remoto: passa-o nas opções de `query()` com um token de acesso pessoal lido do ambiente. O servidor impõe as permissões, mas não a tua política de aprovação, por isso o teu agente decide quando um plano pode ser aprovado; mantém uma pessoa nesse circuito.

Passa o servidor nas opções de `query()`, com um token de acesso pessoal como bearer, lido da variável de ambiente `CHATTEE_PAT`, para que o token nunca fique no teu código:

```js
mcpServers: {
  chattee: {
    type: "http",
    url: "https://chattee.ai/mcp/connect",
    headers: { Authorization: "Bearer " + process.env.CHATTEE_PAT },
  },
}
```

Permite as ferramentas com `allowedTools: ["mcp__chattee"]` e mantém uma pessoa no circuito para o `approve_plan` — aqui o servidor não recusa nada, por isso é a política do teu próprio agente que impede que um plano seja aprovado sem ninguém o ver.

## A skill do Chattee e o tools.json

A skill do Chattee ensina um agente a trabalhar com o Chattee: o ciclo de construção, a regra da aprovação, o significado de cada resultado e todas as ferramentas. É um ficheiro Markdown, mais um zip para o Claude.ai. O `tools.json` lista as mesmas ferramentas como dados. Um plugin, quando estiver listado, instala a ligação e a skill juntas.

- **Skill para agentes:** [`skill.md`](/docs/mcp/skill.md) ensina a um agente o ciclo de construção, a regra da aprovação e todas as ferramentas, em qualquer cliente que leia Agent Skills (Claude Code, Cursor, Codex, o Claude Agent SDK). A skill está em inglês, porque são os agentes que a leem. O Claude.ai aceita a mesma skill como [`chattee-skill.zip`](/docs/mcp/chattee-skill.zip): carrega-a em **Customize → Skills**.
- **Ferramentas em JSON:** [`tools.json`](/docs/mcp/tools.json) lista todas as ferramentas com o grupo, a permissão, o acesso e os parâmetros de cada uma, para agentes e diretórios que preferem dados a texto.

## Autenticação: OAuth ou tokens de acesso pessoal

Há duas formas de iniciar sessão e um só conjunto de permissões. Os clientes alojados usam OAuth 2.1 e enviam-te para a página de consentimento do Chattee; os outros enviam um token de acesso pessoal. Em ambos os casos, as permissões que concedes decidem que ferramentas funcionam, e revogas uma ligação ou um token na [página Assistentes de IA](/app/ai-assistants).

- **OAuth 2.1** é o que os clientes alojados usam (Claude.ai, ChatGPT, Cursor, o início de sessão `/mcp` do Claude Code). O cliente identifica-se com um documento de metadados de client ID ou por registo dinâmico, prova a posse com PKCE (S256) e envia-te para a página de consentimento do Chattee. A página mostra o nome do cliente com o seu domínio verificado, ou marca como não verificado um cliente que se registou a si próprio e mostra para onde a aprovação te leva de volta. Os tokens de acesso duram 1 hora e os tokens de atualização 30 dias; uma atualização roda o token, e um token reutilizado revoga toda a autorização.
- Os **tokens de acesso pessoal** (`chattee_pat_…`) são para clientes que enviam um cabeçalho: o Claude Code com `--header`, o Codex, o Agent SDK, scripts. Cria-os na **[página Assistentes de IA](/app/ai-assistants)**, com as permissões que quiseres e uma data de expiração opcional. O token é mostrado uma vez e guardado em hash. Revoga-o na mesma página.

| Permissão | O que permite | Ferramentas |
|---|---|---|
| `projects:read` | listar e ler áreas de trabalho, projetos, conversas, execuções, registos, ficheiros, modelos e o estado das publicações | `list_workspaces`, `list_projects`, `get_project`, `list_chats`, `get_chat`, `wait_for_run`, `get_run_logs`, `get_release_status`, `list_templates`, `get_template`, `list_files`, `read_file`; também: `create_project`, `send_message` e `refine_plan` com anexos |
| `projects:write` | criar projetos e conversas, enviar mensagens, aprovar e rever planos, responder a perguntas, interromper, continuar e repetir execuções | `create_project`, `create_chat`, `send_message`, `approve_plan`, `refine_plan`, `answer_question`, `stop_run`, `continue_run`, `retry_run`; também: `wait_for_run` quando o teu cliente mostra a pergunta do agente como formulário |
| `projects:delete` | eliminar projetos e conversas (um projeto pede o nome exato como confirmação) | `delete_project`, `delete_chat` |
| `publish` | publicar em Ao vivo, restaurar uma versão, aplicar variáveis de ambiente em Ao vivo | `publish_project`; também: `set_env_vars` com `env: live` |
| `templates` | exportar um projeto como modelo; mudar o nome, descrever, etiquetar, publicar e eliminar os teus modelos | `export_project_as_template`, `update_template`, `delete_template` |
| `files:write` | escrever e eliminar ficheiros no Rascunho de um projeto | `write_file`, `delete_file` |
| `config` | variáveis de ambiente, recursos geridos, criação de recursos, consultas à base de dados só de leitura | `list_env_vars`, `set_env_vars`, `list_resources`, `provision_resource`, `query_database` |
| `usage:read` | o saldo de créditos | `get_credits` |

**Privilégio mínimo:** um token só com `projects:read` e `usage:read` pode ver tudo e não altera nada; acrescenta `projects:write` para construir, e `publish` só se o teu assistente tiver de pôr alterações em Ao vivo.

Uma ferramenta chamada sem a sua permissão responde com um resultado `insufficient_scope` que indica a permissão e onde a concedes; nada é alterado. As apps ligadas e os tokens estão listados, e revogam-se, na [página Assistentes de IA](/app/ai-assistants).

## Referência das ferramentas MCP

O servidor MCP do Chattee tem 35 ferramentas MCP («MCP tools») em oito grupos, listadas com a permissão que cada uma exige e o que pode fazer aos teus dados. Cada resultado traz Markdown e dados estruturados, e cada link devolvido (conversa no builder, pré-visualização do Rascunho, URL de Ao vivo) é absoluto, para o teu assistente to passar.

### Conta e áreas de trabalho

Em nome de quem constróis: as tuas áreas de trabalho e os créditos que uma construção vai gastar.

| Ferramenta | O que faz | Permissão | Acesso |
|---|---|---|---|
| `list_workspaces` | Lista as áreas de trabalho a que pertences; a primeira por ordem alfabética é a predefinida. | `projects:read` | Só leitura |
| `get_credits` | Mostra o saldo de créditos que a próxima construção vai gastar e o limite de créditos por execução. | `usage:read` | Só leitura |

### Projetos

Um projeto é uma app web, com a sua própria pré-visualização do Rascunho e o seu URL de Ao vivo.

| Ferramenta | O que faz | Permissão | Acesso |
|---|---|---|---|
| `list_projects` | Lista os projetos de uma área de trabalho com o estado da implementação e links; `query` pesquisa pelo nome. | `projects:read` | Só leitura |
| `get_project` | Mostra os módulos, o estado do Rascunho e de Ao vivo, as alterações por publicar, a conversa com uma execução em curso e links. | `projects:read` | Só leitura |
| `create_project` | Cria um projeto a partir de um pedido (o planeamento começa logo) ou de um modelo. | `projects:write`¹ | Altera dados |
| `delete_project` | Elimina um projeto de vez; pede o nome exato como confirmação. | `projects:delete` | Substitui ou elimina |

¹ Com anexos, `create_project`, `send_message` e `refine_plan` também precisam de `projects:read`.

### Conversas

Cada conversa é um diálogo com o agente; um projeto faz uma coisa de cada vez.

| Ferramenta | O que faz | Permissão | Acesso |
|---|---|---|---|
| `list_chats` | Lista as conversas de um projeto pela atividade mais recente. | `projects:read` | Só leitura |
| `create_chat` | Abre uma conversa nova ou devolve a vazia; nunca entrega a conversa ocupada. | `projects:write` | Altera dados |
| `get_chat` | Lê a transcrição como linhas tipificadas (texto, plano, pergunta, resumo final) mais o estado da execução; recua página a página com `before`. | `projects:read` | Só leitura |
| `delete_chat` | Elimina uma conversa; é recusado enquanto tiver uma execução por resolver. | `projects:delete` | Substitui ou elimina |

### Execuções

Inicia uma execução, espera pelos pontos de decisão e transmite as tuas decisões sobre o plano e sobre as perguntas do agente.

| Ferramenta | O que faz | Permissão | Acesso |
|---|---|---|---|
| `send_message` | Inicia uma execução (`mode: plan` ou `edit`) ou passa feedback à que está a decorrer; uma conversa grande que ficou parada continua numa nova. | `projects:write`¹ | Altera dados |
| `wait_for_run` | Espera por um ponto de decisão (plano, pergunta, pausa, conclusão, falha) ou pelo tempo limite, e vai transmitindo o progresso. | `projects:read` | Altera dados² |
| `approve_plan` | Transmite o teu sim ao plano; implementa e inicia a construção. | `projects:write` | Altera dados |
| `refine_plan` | Transmite o teu feedback sobre o plano; o agente revê-o. | `projects:write`¹ | Altera dados |
| `answer_question` | Transmite a tua resposta a uma pergunta do agente; nunca um palpite. | `projects:write` | Altera dados |
| `stop_run` | Interrompe a execução, ou termina uma que está em pausa no limite de créditos. | `projects:write` | Substitui ou elimina³ |
| `continue_run` | Retoma uma execução em pausa; aumenta o orçamento só até um total que tu indiques. | `projects:write` | Altera dados |
| `retry_run` | Volta a correr uma execução interrompida ou falhada, na mesma conversa. | `projects:write` | Altera dados |
| `get_run_logs` | Lê as chamadas de ferramentas da execução, o registo de implementação ou o registo de um contentor; avisa quando uma resposta foi cortada. | `projects:read` | Só leitura |

¹ Com anexos, `create_project`, `send_message` e `refine_plan` também precisam de `projects:read`.

² `wait_for_run` só envia a resposta que tu dás quando o teu cliente mostra a pergunta do agente como formulário.

³ `stop_run` termina a execução em curso, ou uma em pausa no limite de créditos; o trabalho já feito fica no Rascunho.

### Publicação

Passa o Rascunho para Ao vivo, acompanha a versão ou volta a uma versão anterior.

| Ferramenta | O que faz | Permissão | Acesso |
|---|---|---|---|
| `get_release_status` | O Rascunho face a Ao vivo, a versão que está em Ao vivo, o histórico e os bloqueios; espera por uma versão com `wait_seconds`. | `projects:read` | Só leitura |
| `publish_project` | Publica o Rascunho em Ao vivo, ou restaura uma versão anterior. | `publish` | Substitui ou elimina |

### Modelos

Começa um projeto a partir de um modelo, ou transforma um projeto implementado num modelo.

| Ferramenta | O que faz | Permissão | Acesso |
|---|---|---|---|
| `list_templates` | Lista os modelos de que podes partir: os teus, os publicados ou ambos. | `projects:read` | Só leitura |
| `get_template` | Mostra a descrição, as etiquetas, os módulos e a pré-visualização de um modelo. | `projects:read` | Só leitura |
| `export_project_as_template` | Congela um projeto implementado como modelo privado, com a sua própria base de dados vazia. | `templates` | Altera dados |
| `update_template` | Muda o nome, a descrição ou as etiquetas de um modelo, ou publica-o ou retira-o da publicação. | `templates` | Altera dados |
| `delete_template` | Elimina um modelo de vez; retira-o primeiro da publicação. | `templates` | Substitui ou elimina |

### Ficheiros

Lê o código ou faz uma alteração pequena e segura; para algo maior, envia uma edição para o agente a construir e verificar.

| Ferramenta | O que faz | Permissão | Acesso |
|---|---|---|---|
| `list_files` | Mostra uma árvore de ficheiros, ou pesquisa nomes e conteúdos. | `projects:read` | Só leitura |
| `read_file` | Lê uma janela de um ficheiro de texto, no máximo 200 000 caracteres por chamada. | `projects:read` | Só leitura |
| `write_file` | Escreve um ficheiro inteiro do Rascunho, criando-o se não existir; conta como alteração por publicar. | `files:write` | Substitui ou elimina |
| `delete_file` | Elimina um ficheiro do Rascunho. | `files:write` | Substitui ou elimina |

### Configuração e dados

As definições da app, os seus recursos geridos e consultas à base de dados só de leitura.

| Ferramenta | O que faz | Permissão | Acesso |
|---|---|---|---|
| `list_env_vars` | Lista as variáveis por módulo; o valor de um segredo volta como `null`. | `config` | Só leitura |
| `set_env_vars` | Junta as variáveis às existentes; só remove uma com `remove: true`; `apply` recria os contentores. | `config`⁴ | Substitui ou elimina |
| `list_resources` | Lista a base de dados gerida, o armazenamento de ficheiros, a autenticação e o e-mail, com o estado de cada um. | `config` | Só leitura |
| `provision_resource` | Adiciona um recurso gerido fora de um plano. | `config` | Altera dados |
| `query_database` | Mostra o esquema ou executa uma instrução só de leitura no Rascunho ou em Ao vivo (`env` é obrigatório; as leituras em Ao vivo ficam registadas). | `config` | Só leitura |

⁴ Com `env: live`, `set_env_vars` também precisa de `publish`.

## O ciclo de construção e a aprovação humana

Cada construção segue o mesmo ciclo: uma execução de planeamento, a tua aprovação, a construção e uma publicação quando a pedires. O teu assistente conduz o ciclo com poucas ferramentas e espera entre os passos, porque uma construção demora 5–90 minutos. Duas decisões são sempre tuas: aprovar um plano e gastar mais do que o orçamento de uma execução.

1. `create_project` (ou `send_message` numa conversa existente com `mode: plan`) inicia uma execução de planeamento.
2. `wait_for_run` responde quando o plano está pronto. O teu assistente mostra-te o **plano completo** e o link para o builder.
3. Dizes que sim — `approve_plan` — ou dás feedback — `refine_plan`. A aprovação implementa os contentores e inicia a construção.
4. `wait_for_run`, repetidamente, até a execução terminar. Uma execução demora 5–90 minutos; cada espera termina ao fim de 240 segundos, no máximo, com o progresso até aí, e um resultado `timed_out_waiting` quer apenas dizer «chama outra vez».
5. Se o agente perguntar alguma coisa (`awaiting_input`), o teu assistente transmite-te a pergunta e a tua resposta volta por `answer_question`. Os clientes que suportam elicitação MCP recebem a pergunta como formulário.
6. Quando a execução termina, voltam o resumo final e o link da pré-visualização do Rascunho. `publish_project` quando o pedires; o URL de Ao vivo volta da mesma forma.

As pausas por orçamento, um cartão expirado ou a falta de créditos terminam uma espera com um resultado `escalate` e links para o builder. O orçamento de uma execução em pausa sobe só até um total que tu indiques: o teu assistente passa o teu número com `continue_run` e só o guarda como predefinição se o disseres à parte. Uma execução em pausa no limite termina sozinha ao fim de 30 minutos se ninguém decidir, e `stop_run` termina-a de imediato; o trabalho fica guardado, e a tua próxima mensagem continua-o como uma nova execução com um novo limite de créditos. Os créditos compram-se no builder; nada neste endpoint os compra.

## Limites e limitação de pedidos

Cada limite abaixo é imposto pelo servidor e indicado na resposta quando o atinges, para o teu assistente poder esperar ou restringir a chamada em vez de adivinhar. As esperas têm um teto para nenhum cliente perder a chamada, as chamadas são limitadas por utilizador e as leituras longas chegam em janelas que vais percorrendo.

- `wait_for_run` espera 45 segundos por predefinição; `get_release_status` espera 0 segundos por predefinição, por isso responde de imediato se não passares `wait_seconds`. Ambos esperam no máximo 240 segundos por chamada. Mais não serve de nada: o Claude Code abandona uma chamada de ferramenta HTTP ao fim de cinco minutos sem progresso.
- 120 chamadas por minuto e por utilizador, somando todos os teus tokens e apps ligadas; acima disso, um resultado `rate_limited` com `retry_after_seconds`. Uma espera em curso mantém a execução a andar.
- 20 esperas simultâneas por utilizador, uma execução por projeto de cada vez e o limite de projetos do teu plano.
- Anexos: até 10 por mensagem, texto até 256 KB e ficheiros binários até 5 MB cada, e no máximo 20 MB no total por mensagem.
- `read_file` devolve no máximo 200 000 caracteres por chamada. Uma janela mais longa volta com `truncated: true` e `next_offset_line`, e o resultado explica como continuar a ler com `offset_line` e `limit_lines`.
- `get_chat` encurta as mensagens longas (`truncated: true`) e devolve as mais antigas através de `before`: passa o `next_before` do resultado para ler a página anterior.
- `get_run_logs` limita cada resposta e avisa quando a cortou; restringe-a com `tail` ou `source`.
- As chaves de idempotência das ferramentas que alteram dados ficam memorizadas durante 24 horas; um reinício do serviço esquece-as.

## Segurança

O endpoint é a única superfície pública do servidor MCP do Chattee; a verificação dos tokens e todas as chamadas ao Chattee correm atrás dele, no mesmo servidor. Os tokens são guardados em hash, as permissões verificadas em cada chamada, o conteúdo passa pelas verificações de segurança do builder e cada chamada de ferramenta fica num registo de auditoria.

- O endpoint é a única superfície pública. A verificação dos tokens e todas as chamadas ao plano de controlo do Chattee correm em loopback, dentro do mesmo servidor.
- Os tokens são guardados em hash. O OAuth usa PKCE S256, URIs de redirecionamento exatos (exceto as portas de loopback, segundo o RFC 8252), códigos de uso único e tokens de atualização rotativos; a página de consentimento mostra o domínio verificado de um cliente e marca como não verificado um cliente que se registou a si próprio, por isso um cliente que se faça passar por outro fica à vista.
- As permissões são impostas em cada chamada; o endpoint recusa a chave API da conta.
- O conteúdo passa pelas mesmas verificações de segurança (guardrails) do builder. Um bloqueio por essas verificações revoga todos os tokens e todas as apps ligadas da conta.
- Cada chamada de ferramenta fica num registo de auditoria, guardado durante 30 dias. Na conversa do builder, uma mensagem que o teu assistente enviou fica marcada com o cliente que a enviou, por exemplo «via Claude Code».
- Revoga um token ou uma app ligada a qualquer momento na [página Assistentes de IA](/app/ai-assistants).

## Resolução de problemas

A maioria dos erros indica a sua própria solução: o resultado traz um código, uma frase sobre o que aconteceu e muitas vezes um link para o builder. Abaixo estão os códigos que mais provavelmente vais encontrar, cada um com o que fazer. Se uma chamada falhar sem código, avisa-nos e indica a hora da chamada.

- **401 `invalid_token`** — o token foi revogado, expirou ou é a chave API da conta. Cria um token de acesso pessoal, ou volta a ligar para o cliente iniciar sessão de novo.
- **`token_inactive`** — a credencial deixou de funcionar durante a chamada: foi revogada ou expirou. Uma app ligada volta a iniciar sessão no pedido seguinte (se não o fizer, liga-a de novo); um token de acesso pessoal não tem recuperação, por isso cria um novo na [página Assistentes de IA](/app/ai-assistants) e usa-o no lugar do antigo.
- **`email_unconfirmed`** — o endereço de e-mail da tua conta Chattee ainda não está confirmado. Confirma-o com o link do e-mail que o Chattee te enviou (o builder pode enviá-lo outra vez) e tenta de novo.
- **`account_blocked`** — a tua conta Chattee está suspensa, e nada neste endpoint funciona até ser reativada. [Contacta-nos](/pt/p/contact).
- **`internal_error`** — algo falhou dentro do Chattee. Tenta a chamada mais uma vez; se voltar a falhar, [comunica-nos o erro](/pt/p/contact) com a hora da chamada.
- **`insufficient_scope`** — o resultado indica a permissão em falta. Concede-a no token, ou volta a ligar a app e aceita a permissão.
- **`rate_limited`** — espera os `retry_after_seconds`; nada se perdeu e a execução continua.
- **`conflict_busy`** — outra conversa do projeto está a usar o espaço de trabalho; o resultado indica qual. Espera por ela, ou interrompe essa execução.
- **`attachment_invalid`** — o `base64` de um anexo não é base64 válido. Codifica o ficheiro outra vez, ou envia um ficheiro de texto como `text`.
- **`too_many_tasks`** — a tua conta tem demasiadas tarefas de longa duração abertas no servidor (em clientes que usam tarefas MCP). Deixa algumas terminar ou cancela-as, e tenta de novo; as execuções em si não são afetadas.
- **O Cursor está sempre a pedir para iniciar sessão** — o Cursor ignora os cabeçalhos `Authorization` quando um servidor oferece OAuth. Remove o cabeçalho e inicia sessão.
- **O Codex indica que o tempo se esgotou** — o Codex termina as chamadas de ferramentas aos 60 segundos. Mantém a espera predefinida; não passes `timeout_seconds` acima de 50.
- **503 `introspection_unavailable`** — o Chattee não conseguiu verificar tokens durante um momento. Tenta de novo daqui a alguns segundos; o cliente mantém o token.

## Histórico de alterações

- **2026-10-15** — A documentação e a página de apresentação estão agora também em espanhol, francês e português, além de inglês e alemão: `/es/docs/mcp`, `/fr/docs/mcp` e `/pt/docs/mcp`, cada uma com a sua versão em Markdown. A skill para agentes e o `tools.json` continuam em inglês.
- **2026-10-02** — Uma execução em pausa no limite de créditos termina sozinha ao fim de 30 minutos se ninguém decidir, e `stop_run` termina-a de imediato (resultado `ended`); `get_credits` indica o limite com que uma execução começa e o máximo até onde pode subir; `create_project` recebe o limite da primeira execução e `approve_plan` a margem própria da construção, sempre só como um número que tu indicas.
- **2026-10-01** — As ferramentas aparecem numa tabela por grupo, com a permissão de cada uma e o que pode fazer aos teus dados; exemplos de pedidos tirados de execuções reais; a skill do Chattee (`skill.md`, e um zip para o Claude.ai) e o `tools.json`; um assistente aumenta o orçamento de uma execução em pausa só até um total que tu indiques. Claude Code: o comando de configuração adiciona o Chattee para o teu utilizador (`--scope user`), e `claude mcp login chattee` inicia sessão a partir da shell. Os passos do Claude.ai e do ChatGPT seguem os menus atuais das duas apps.
- **2026-09-26** — Primeira versão: 35 ferramentas, OAuth 2.1 com PKCE e tokens de acesso pessoal, as duas revisões do protocolo, elicitação e tarefas MCP para os clientes que as declaram, e um resumo final no fim de cada construção.

## Perguntas frequentes

### O que pode fazer o servidor MCP do Chattee?

Permite que o teu assistente de IA construa uma app web completa no Chattee a partir de uma descrição: criar o projeto, transmitir-te o plano para aprovares, acompanhar a construção, entregar-te a pré-visualização do Rascunho e publicar em Ao vivo. Também pode ler e alterar ficheiros, gerir variáveis de ambiente e recursos geridos, consultar a base de dados só em leitura e partir de modelos.

### Como começo a usar o servidor MCP do Chattee?

Cria uma conta Chattee gratuita, adiciona https://chattee.ai/mcp/connect ao teu assistente (um comando no Claude Code, um conector personalizado no Claude.ai, uma entrada JSON no Cursor), inicia sessão com OAuth ou com um token de acesso pessoal e pede ao teu assistente para construir alguma coisa. A configuração de cada cliente está nesta página.

### Que assistentes de IA funcionam com o servidor MCP do Chattee?

O Claude Code, o Claude.ai, o Claude Desktop e as apps móveis do Claude, o Cursor, o Codex CLI, o ChatGPT no Developer mode e os agentes criados com o Claude Agent SDK. Qualquer outro cliente MCP que fale Streamable HTTP também funciona; o mcp-remote faz a ponte para um cliente que só fala stdio.

### O servidor MCP do Chattee é gratuito?

Ligar é gratuito. Construir gasta os créditos do teu plano Chattee, tal como construir no navegador, e o plano gratuito inclui créditos para começar. Uma execução que atinge o orçamento fica em pausa; o seu limite sobe só até um total que tu indiques, e os créditos compram-se no builder.

### O Chattee implementa e aloja a app?

Sim. Cada projeto tem uma pré-visualização do Rascunho, e ao publicares passa para Ao vivo, num URL em chattee.ai ou no teu próprio domínio, com uma base de dados Postgres gerida, início de sessão, armazenamento de ficheiros e e-mail quando a app precisa deles. O teu assistente nunca lida com servidores, contentores nem scripts de implementação.

### O meu assistente pode aprovar um plano sozinho?

Não. Cada plano é-te mostrado e és tu que o aprovas, na tua conversa ou no builder. As descrições das ferramentas proíbem a autoaprovação, e podes limitar um token a permissões só de leitura se quiseres ter a certeza.

### O meu assistente pode aumentar o orçamento de uma execução?

Pode, mas só até um total que tu indiques. Uma execução que atinge o orçamento fica em pausa, e o teu assistente dá-te o link para o builder. Se tu próprio lhe disseres um novo total, ele continua a execução exatamente com esse limite, e só o guarda como tua predefinição depois de um sim à parte. Se ninguém decidir, a execução em pausa termina sozinha ao fim de 30 minutos e mantém o trabalho; a tua próxima mensagem continua-o como uma nova execução. O teu assistente nunca compra créditos: os planos e os créditos compram-se no builder.

### Qual é a diferença em relação a deixar um agente de programação construir a app sozinho?

Um agente de programação, sozinho, escreve código no teu computador, e o alojamento, a base de dados, o início de sessão, o e-mail e as implementações ficam por tua conta. Através do Chattee, o teu assistente passa a descrição a um builder que planeia, constrói, implementa e aloja a app inteira, enquanto tu aprovas o plano e decides quando ela fica online.

### Que versões do protocolo MCP são suportadas?

As duas revisões atuais: 2025-11-25, a que usa sessões e que todos os clientes disponíveis hoje falam, e 2026-07-28, a sem estado, com tarefas e resultados input-required. O transporte é Streamable HTTP. Não há pacote stdio; o mcp-remote faz a ponte para um cliente que precise de um.

### Posso usar a chave API da minha conta em vez de um token?

Não. O endpoint recusa a chave da conta de propósito: um token de acesso pessoal tem permissões delimitadas e pode ser revogado, e a chave da conta não tem nenhuma das duas coisas. Cria um token na página Assistentes de IA, ou deixa o cliente iniciar sessão com OAuth.

### Quanto tempo demora uma construção?

Uma app completa demora 5–90 minutos; uma pequena edição, poucos. O wait_for_run responde em cada ponto de decisão e, fora disso, ao fim de 240 segundos no máximo, por isso o teu assistente continua a perguntar até a execução precisar de ti.

### O que acontece se o meu assistente perder a ligação durante uma construção?

Do lado do Chattee, nada: as execuções vivem no backend, não na ligação. Volta a ligar e chama o wait_for_run outra vez, ou abre a conversa no builder, onde a mesma execução continua.

### Esta documentação existe noutras línguas?

Sim: em inglês, em /docs/mcp e /mcp, e também em alemão, espanhol e francês, nos mesmos endereços com /de, /es ou /fr à frente.