> ## Documentation Index
> Fetch the complete documentation index at: https://developer.z-api.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Como conectar

> Conecte sua conta Z-API ao servidor MCP e autorize seu app de IA

O servidor MCP da Z-API pode ser conectado a qualquer aplicativo de IA compatível com MCP (Claude, ChatGPT, agentes customizados, entre outros). O processo é sempre parecido: adicionar o servidor como um conector/ferramenta personalizada e autorizar o acesso à sua instância.

Abaixo mostramos o passo a passo usando o **Claude** como exemplo, por ser um dos apps de IA mais usados — mas a lógica é a mesma em qualquer cliente MCP.

### 1. Abra as configurações de Conectores

No Claude, vá em **Configurações → Conectores**. Clique no menu **Adicionar**, no canto superior direito, e selecione **Adicionar conector personalizado**.

<Frame>
  <img src="https://mintcdn.com/z-api-8aa3bb40/D9KVw72q9v4_27Pk/images/claude-conectores-adicionar.png?fit=max&auto=format&n=D9KVw72q9v4_27Pk&q=85&s=dc45413767741438f281f009c7f4f345" alt="Tela de Conectores do Claude com o menu Adicionar aberto, mostrando as opções Navegar conectores e Adicionar conector personalizado" width="861" height="643" data-path="images/claude-conectores-adicionar.png" />
</Frame>

### 2. Preencha nome e URL do servidor

Na janela **Adicionar conector personalizado**, informe:

* **Nome**: o nome que você preferir — usamos `Z-API` apenas como sugestão para facilitar a identificação depois
* **URL do servidor MCP**: `https://mcp.z-api.io/mcp`

<Frame>
  <img src="https://mintcdn.com/z-api-8aa3bb40/D9KVw72q9v4_27Pk/images/claude-adicionar-conector-personalizado.png?fit=max&auto=format&n=D9KVw72q9v4_27Pk&q=85&s=6363fc5585817d71b499be129540ad4d" alt="Formulário Adicionar conector personalizado do Claude preenchido com o nome Z-API e a URL https://mcp.z-api.io/mcp" style={{borderRadius: "8px"}} width="520" height="536" data-path="images/claude-adicionar-conector-personalizado.png" />
</Frame>

Clique em **Adicionar**. O conector Z-API aparecerá na lista de conectores, ainda como **não conectado**.

### 3. Vincule sua instância

Abra o conector **Z-API** na lista e clique em **Vincular**.

<Frame>
  <img src="https://mintcdn.com/z-api-8aa3bb40/D9KVw72q9v4_27Pk/images/claude-vincular-zapi.png?fit=max&auto=format&n=D9KVw72q9v4_27Pk&q=85&s=d06ce86804297826cd4751a4d15534f1" alt="Página do conector Z-API no Claude mostrando o botão Vincular antes de conectar" width="947" height="705" data-path="images/claude-vincular-zapi.png" />
</Frame>

Isso abre uma aba do navegador para autorizar a conexão. Você precisa estar **logado na plataforma da Z-API** para prosseguir — caso ainda não esteja, será solicitado o login antes de exibir a lista de instâncias.

Escolha qual **instância** da sua conta Z-API deseja autorizar. Localize a instância desejada na lista (você pode usar a busca) e clique em **Selecionar**.

<Frame>
  <img src="https://mintcdn.com/z-api-8aa3bb40/D9KVw72q9v4_27Pk/images/claude-selecionar-instancia.png?fit=max&auto=format&n=D9KVw72q9v4_27Pk&q=85&s=da4e9f68da345125eb7bc8842f04056d" alt="Tela Qual instância deseja conectar ao Claude, com uma lista de instâncias Z-API e o botão Selecionar em cada linha" width="823" height="825" data-path="images/claude-selecionar-instancia.png" />
</Frame>

<Info>
  Se a instância selecionada estiver **desconectada do WhatsApp** (sem o QR Code lido), vincular o conector MCP não conecta o WhatsApp automaticamente. Você ainda precisa acessar o painel da Z-API e ler o QR Code normalmente, para colocar a instância online.
</Info>

Depois de selecionar a instância, confirme em **Abrir Claude** (ou **Abrir aplicativo para desktop**, caso esteja usando o app desktop) para retornar automaticamente ao Claude.

<Frame>
  <img src="https://mintcdn.com/z-api-8aa3bb40/D9KVw72q9v4_27Pk/images/claude-conectado-retorno.png?fit=max&auto=format&n=D9KVw72q9v4_27Pk&q=85&s=f69120825e8610e60c77a6ba8b903375" alt="Tela de confirmação Conectado, indicando que o Claude será aberto de volta automaticamente" style={{borderRadius: "8px", maxWidth: "400px", width: "100%"}} width="544" height="713" data-path="images/claude-conectado-retorno.png" />
</Frame>

### 4. Pronto para usar

Ao selecionar a instância, a conexão é estabelecida automaticamente, disponibilizando todos os endpoints da Z-API compatíveis com o MCP, como envio de mensagens de texto, imagens, vídeos, gerenciamento de grupos e demais funcionalidades atualmente suportadas, para uso direto pelo Claude.

Para usar o conector em uma conversa, clique no ícone **+** ao lado do campo de mensagem, vá em **Conectores** e ative o toggle da **Z-API**.

<Frame>
  <img src="https://mintcdn.com/z-api-8aa3bb40/D9KVw72q9v4_27Pk/images/claude-ativar-zapi-conversa.png?fit=max&auto=format&n=D9KVw72q9v4_27Pk&q=85&s=51ea1874de1ea97444a023bb55951544" alt="Menu de conectores do Claude no campo de mensagem com o toggle da Z-API ativado" style={{borderRadius: "8px"}} width="679" height="442" data-path="images/claude-ativar-zapi-conversa.png" />
</Frame>

Pronto! Agora a IA já está conectada à sua instância Z-API. Basta pedir, em linguagem natural, que ela envie uma mensagem, uma imagem, crie um grupo ou execute qualquer uma das ações disponíveis — ela vai identificar a ferramenta certa e fazer a requisição por você.

<Info>
  Depois de conectado, o app de IA passa a aparecer na aba **Apps conectados**, dentro do painel da instância na Z-API. É por lá que você pode acompanhar quando foi conectado, o último uso e remover o acesso quando quiser.
</Info>

***

## Autenticação

A conexão é feita via **OAuth**, vinculando a instância Z-API escolhida diretamente ao conector no seu app de IA. A IA nunca acessa senha ou credenciais do WhatsApp diretamente — apenas os endpoints autorizados da instância selecionada.

<Warning>
  Desconectar o **WhatsApp** da instância (ler o QR Code novamente) **não revoga** automaticamente o acesso do app de IA. As duas conexões são independentes.

  Para revogar o acesso da IA, vá até a aba **Apps conectados** no painel da sua instância Z-API e remova o app por lá — isso encerra o acesso imediatamente, sem precisar mexer nas configurações do app de IA.
</Warning>

***

## Perguntas frequentes

<AccordionGroup>
  <Accordion title="Desconectei o WhatsApp da instância (li o QR Code novamente) no painel da Z-API. Isso desconecta o app de IA também?">
    Não. São duas conexões independentes. Desconectar o WhatsApp da instância não remove o app de IA nem revoga sua autorização — o acesso continua ativo até que você o remova manualmente na aba **Apps conectados**, no painel da instância.
  </Accordion>

  <Accordion title="Como revogo o acesso do app de IA sem desconectar o WhatsApp?">
    Acesse o painel da sua instância na Z-API, vá até a aba **Apps conectados** e remova o app desejado por lá. Isso encerra o acesso imediatamente, sem afetar a conexão do WhatsApp.
  </Accordion>

  <Accordion title="A IA não consegue enviar mensagem — o que verificar?">
    **(1)** O conector Z-API está ativado para essa conversa? **(2)** A instância selecionada está conectada e ativa no painel da Z-API? **(3)** A vinculação/token expirou? Se sim, desvincule e vincule novamente o conector nas configurações do app de IA. Persistindo, acione o suporte técnico.
  </Accordion>

  <Accordion title="Preciso adicionar o conector em cada conversa?">
    Não. Depois de adicionado e vinculado uma vez, o conector fica disponível para ser ativado em qualquer conversa nova através do menu de conectores.
  </Accordion>
</AccordionGroup>