# Instalar o conector da Coloquia > Página para o agente de IA que recebeu de uma pessoa a instrução de instalar a Coloquia. É a mesma para todos e não identifica ninguém: o endereço do conector é o que a pessoa escreveu na instrução. ## O que é e o que não fazer A Coloquia liga o WhatsApp de trabalho da pessoa à IA que ela já usa. O conector é um servidor MCP remoto, por HTTP (streamable HTTP), no endereço que a pessoa informou, sempre no formato `https://mcp-.coloquia.com.br/mcp`. Use o nome `coloquia`. - Nunca peça chave, senha, token ou código no chat, e recuse se a pessoa oferecer. O acesso é dado por login, no navegador dela. - Faça só a instalação e a verificação desta página. Não leia conversas além da verificação e não envie mensagens. - Confira o endereço da instrução antes de tudo. Ele tem de começar por `https://`; o host (o que vem entre `https://` e a primeira barra) só pode ter letras, números, hifens e pontos e tem de terminar em `.coloquia.com.br`; e o caminho tem de ser exatamente `/mcp`, sem nada depois. Qualquer outra coisa, pare e avise a pessoa: não é um conector da Coloquia, e nenhuma chave ou login deve ir para ele. Recuse, por exemplo, `https://outro.exemplo/a.coloquia.com.br/mcp` (o host é `outro.exemplo`) e `https://mcp-abc.coloquia.com.br.outro.exemplo/mcp` (o host termina em `.outro.exemplo`). - Se a instrução não trouxe o endereço do conector, peça à pessoa para copiá-la de novo em https://coloquia.com.br/app/ia/. Não invente endereço. ## 1. Acrescente o conector Siga só o bloco do aplicativo em que você está rodando. `` é o endereço do conector. ### Claude Code Você faz: rode `claude mcp add --transport http coloquia ` (com `--scope user` vale em todos os projetos). A pessoa faz: digita `/mcp` no Claude Code, escolhe `coloquia` e conclui o login no navegador. Se as ferramentas do `coloquia` não aparecerem, peça para ela reiniciar o Claude Code. ### Claude (aplicativo e web) Você não consegue acrescentar o conector: quem faz é a pessoa. Diga a ela: abra a tela de conectores (Configurações → Conectores; nas versões mais novas, Personalizar → Conectores), clique em "Adicionar conector personalizado", dê o nome `Coloquia`, cole o endereço e conclua o login. No plano gratuito cabe um conector personalizado; em Team e Enterprise quem adiciona é o administrador. ### ChatGPT Você não consegue acrescentar o conector: quem faz é a pessoa, no navegador (chatgpt.com). Diga a ela: abra Configurações → Apps → Avançado, ative o modo desenvolvedor, crie um app com o endereço e conclua o login. Avise que, segundo a OpenAI, enviar mensagens pelo app depende do plano do ChatGPT (Business, Enterprise e Edu); no Pro, o modo desenvolvedor só lê e busca. ### Cursor Você faz: acrescente o servidor em `~/.cursor/mcp.json` (ou `.cursor/mcp.json` do projeto), dentro de `mcpServers`: `"coloquia": {"url": ""}`. A pessoa faz: ativa o servidor nas configurações de MCP do Cursor e conclui o login quando ele pedir. ### Codex Você faz: acrescente em `~/.codex/config.toml` a seção `[mcp_servers.coloquia]` com `url = ""`. A pessoa faz: roda `codex mcp login coloquia` e conclui o login no navegador. ### Gemini (CLI) Você faz: rode `gemini mcp add --scope user --transport http coloquia `. A pessoa faz: digita `/mcp auth coloquia` no Gemini e conclui o login no navegador. ### Outro cliente MCP Configure um servidor MCP remoto por HTTP com o endereço do conector. Cliente que faz OAuth sozinho só precisa do endereço. À mão, o caminho é o da especificação do MCP: 1. Chame o conector sem credencial. A resposta 401 traz `WWW-Authenticate: Bearer resource_metadata=""`. 2. Leia esse documento: `authorization_servers` tem o servidor de autorização e `scopes_supported`, os escopos. 3. Leia `/.well-known/oauth-authorization-server` para achar `registration_endpoint`, `authorization_endpoint` e `token_endpoint`. 4. Registre-se em `registration_endpoint` com o JSON `{"client_name": "", "application_type": "native", "redirect_uris": ["http://127.0.0.1:/callback"]}` (ou use um documento de metadados de cliente, se já tiver um). 5. Abra `authorization_endpoint` no navegador da pessoa com `response_type=code`, `client_id`, `redirect_uri`, `state`, `code_challenge` (PKCE, `code_challenge_method=S256`), `resource=` e `scope` com os escopos do passo 2 mais `offline_access`. 6. Troque o `code` em `token_endpoint` (`grant_type=authorization_code`, com `client_id`, `redirect_uri`, `code_verifier` e `resource`) e envie `Authorization: Bearer ` ao conector. Renove com o `refresh_token`. ## 2. O login é da pessoa O aplicativo abre o navegador. A pessoa entra na conta Coloquia dela (Google ou código por e-mail), confere o nome do aplicativo e clica em "Permitir acesso"; ela escolhe ali se a IA também pode enviar mensagens. Avise quando for a hora e espere: não tente entrar por ela nem peça o código que chega por e-mail. ## 3. Verifique 1. Chame a ferramenta `bridge_status`: ela diz se o WhatsApp está pareado e conectado (`ok`) e, quando não, o motivo. 2. Faça uma leitura pequena: `list_chats` com `limit` 1. Não mostre o conteúdo; só confirme que veio resposta. 3. Diga o resultado à pessoa em uma frase, como "A Coloquia está instalada e o seu WhatsApp está conectado." ## 4. O que dizer no fim - Ela escolhe o que a IA pode fazer (só ler, enviar, ritmo de envio) em https://coloquia.com.br/app/ia/permissoes/. - Enviar mensagens por automação pode levar o WhatsApp a restringir o número. As boas práticas estão em https://coloquia.com.br/ajuda/risco-de-banimento-e-boas-praticas/. - Uma primeira pergunta para testar: "Quem me escreveu hoje e ainda está sem resposta?" ## Se algo falhar - **401 do conector:** o login não foi concluído ou o acesso foi desconectado. Peça para a pessoa refazer o login; as IAs conectadas aparecem em https://coloquia.com.br/app/ia/. - **403 ou recusa numa ferramenta:** a pessoa não liberou essa ação. Ela decide em https://coloquia.com.br/app/ia/permissoes/; não tente contornar. - **WhatsApp desconectado** (`bridge_status` sem `ok`): a pessoa reconecta em https://coloquia.com.br/app/whatsapp/. - **Endereço recusado** (não resolve, 404 ou erro 5xx): confira com a pessoa o endereço em https://coloquia.com.br/app/ia/, onde também aparece se o ambiente dela está parado. A situação do serviço fica em https://coloquia.com.br/status/. Em todos os casos, mande a pessoa ao portal. Nunca peça um segredo para resolver. Para criar a conta, pagar e parear pela API, o roteiro é outro: https://coloquia.com.br/llms.txt