Z-API · paolamayuri · Jul 10, 2026
diff --git a/docs.json b/docs.json
@@ -75,6 +75,13 @@
                 "group": "Segurança",
                 "pages": ["security/introduction", "security/ip-block", "security/twofactor", "security/client-token"]
               },
+              {
+                "group": "MCP Server",
+                "pages": [
+                  "mcp/introduction",
+                  "mcp/how-to-connect"
+                ]
+              },
               {
                 "group": "Dicas",
                 "pages": [
@@ -162,6 +169,13 @@
                 "group": "Security",
                 "pages": ["en/security/introduction", "en/security/ip-block", "en/security/twofactor", "en/security/client-token"]
               },
+              {
+                "group": "MCP Server",
+                "pages": [
+                  "en/mcp/introduction",
+                  "en/mcp/how-to-connect"
+                ]
+              },
               {
                 "group": "Tips",
                 "pages": [

diff --git a/en/mcp/how-to-connect.mdx b/en/mcp/how-to-connect.mdx
@@ -0,0 +1,105 @@
+---
+title: "How to connect"
+description: "Connect your Z-API account to the MCP server and authorize your AI app"
+---
+
+The Z-API MCP server can be connected to any MCP-compatible AI application (Claude, ChatGPT, custom agents, among others). The process is always similar: add the server as a connector/custom tool and authorize access to your instance.
+
+Below we show the step-by-step using **Claude** as an example, since it's one of the most widely used AI apps — but the logic is the same in any MCP client.
+
+### 1. Open Connector settings
+
+In Claude, go to **Settings → Connectors**. Click the **Add** menu in the top right corner, and select **Add custom connector**.
+
+<Frame>
+  <img src="/images/claude-connectors-add.png" alt="Claude's Connectors screen with the Add menu open, showing the options Browse connectors and Add custom connector" />
+</Frame>
+
+### 2. Fill in the server name and URL
+
+In the **Add custom connector** window, enter:
+
+- **Name**: whatever name you prefer — we use `Z-API` here just as a suggestion, to make it easier to identify later
+- **MCP server URL**: `https://mcp.z-api.io/mcp`
+
+<Frame>
+  <img src="/images/claude-add-custom-connector.png" alt="Claude's Add custom connector form filled in with the name Z-API and the URL https://mcp.z-api.io/mcp" style={{borderRadius: "8px"}}/>
+</Frame>
+
+Click **Add**. The Z-API connector will appear in the connectors list, still shown as **not connected**.
+
+### 3. Link your instance
+
+Open the **Z-API** connector in the list and click **Connect**.
+
+<Frame>
+  <img src="/images/claude-connect-zapi.png" alt="Z-API connector page in Claude showing the Connect button before connecting" />
+</Frame>
+
+This opens a browser tab to authorize the connection. You need to be **logged in to the Z-API platform** to proceed — if you aren't, you'll be prompted to log in before the instance list is shown.
+
+Choose which **instance** of your Z-API account you want to authorize. Find the desired instance in the list (you can use the search bar) and click **Select**.
+
+<Frame>
+  <img src="/images/claude-select-instance.png" alt="Which instance would you like to connect to Claude screen, with a list of Z-API instances and a Select button on each row" />
+</Frame>
+
+<Info>
+If the selected instance is **disconnected from WhatsApp** (QR Code not scanned), linking the MCP connector won't connect WhatsApp automatically. You'll still need to go to the Z-API dashboard and scan the QR Code the usual way to bring the instance online.
+</Info>
+
+After selecting the instance, confirm by clicking **Open Claude** (or **Open desktop app**, if you're using the desktop app) to automatically return to Claude.
+
+<Frame>
+  <img src="/images/claude-connected-return.png" alt="Connected confirmation screen, indicating that Claude will automatically open back up" style={{borderRadius: "8px", maxWidth: "400px", width: "100%"}}/>
+</Frame>
+
+### 4. Ready to use
+
+Once the instance is selected, the connection is established automatically, making all MCP-compatible Z-API endpoints available — such as sending text, image, and video messages, group management, and other currently supported features — for direct use by Claude.
+
+To use the connector in a conversation, click the **+** icon next to the message field, go to **Connectors**, and turn on the **Z-API** toggle.
+
+<Frame>
+  <img src="/images/claude-enable-zapi-conversation.png" alt="Claude's connectors menu in the message field with the Z-API toggle turned on" style={{borderRadius: "8px"}}/>
+</Frame>
+
+Done! The AI is now connected to your Z-API instance. Just ask it, in natural language, to send a message, an image, create a group, or perform any of the available actions — it will identify the right tool and make the request for you.
+
+<Info>
+Once connected, the AI app will show up under the **Connected Apps** tab, inside your instance's dashboard on Z-API. That's where you can check when it was connected, its last use, and remove access whenever you want.
+</Info>
+
+---
+
+## Authentication
+
+The connection is made via **OAuth**, linking the chosen Z-API instance directly to the connector in your AI app. The AI never accesses your WhatsApp password or credentials directly — only the authorized endpoints of the selected instance.
+
+<Warning>
+Disconnecting **WhatsApp** from the instance (scanning the QR Code again) does **not** automatically revoke the AI app's access. The two connections are independent.
+
+To revoke the AI's access, go to the **Connected Apps** tab in your Z-API instance dashboard and remove the app from there — this ends access immediately, with no need to change anything in the AI app's settings.
+</Warning>
+
+---
+
+## Frequently asked questions
+
+<AccordionGroup>
+  <Accordion title="I disconnected WhatsApp from the instance (scanned the QR Code again) in the Z-API dashboard. Does that disconnect the AI app too?">
+    No. These are two independent connections. Disconnecting WhatsApp from the instance doesn't remove the AI app or revoke its authorization — access stays active until you remove it manually from the **Connected Apps** tab in the instance dashboard.
+  </Accordion>
+
+  <Accordion title="How do I revoke the AI app's access without disconnecting WhatsApp?">
+    Go to your instance's dashboard on Z-API, open the **Connected Apps** tab, and remove the app from there. This ends access immediately, without affecting the WhatsApp connection.
+  </Accordion>
+
+  <Accordion title="The AI can't send a message — what should I check?">
+    **(1)** Is the Z-API connector enabled for this conversation? **(2)** Is the selected instance connected and active in the Z-API dashboard? **(3)** Has the link/token expired? If so, unlink and reconnect the connector in the AI app's settings. If the issue persists, contact technical support.
+  </Accordion>
+
+  <Accordion title="Do I need to add the connector in every conversation?">
+    No. Once added and linked, the connector remains available to be enabled in any new conversation through the connectors menu.
+  </Accordion>
+</AccordionGroup>
diff --git a/en/mcp/introduction.mdx b/en/mcp/introduction.mdx
@@ -0,0 +1,83 @@
+---
+title: "Introduction"
+description: "Connect your AI to WhatsApp using the Z-API MCP server"
+---
+
+## What is the Z-API MCP?
+
+The Z-API MCP is a server that exposes WhatsApp operations as ready-to-use tools for any MCP-compatible AI — Claude, ChatGPT, custom agents, and others.
+
+Instead of calling the REST API directly, the AI talks to the MCP server, which then executes the actions on your Z-API instance.
+
+<Info>
+**New to MCP?** MCP (Model Context Protocol) is an open standard that defines how AIs connect to external systems. It works like a "skills menu": the AI asks what the server can do, chooses the action, and sends the required data.
+</Info>
+
+---
+
+## What you can do
+
+Today the Z-API MCP exposes 9 tools, split into two groups:
+
+### Messages
+
+| Tool | What it does |
+|---|---|
+| **Send-text** | Sends a text message to a number or group |
+| **Send-image** | Sends an image (link or Base64), with optional caption |
+| **Send-video** | Sends a video (link or Base64), with optional caption |
+
+### Groups
+
+| Tool | What it does |
+|---|---|
+| **Group-create** | Creates a new group with the given participants |
+| **Group-add-participant** | Adds new members to an existing group |
+| **Group-remove-participant** | Removes members from a group |
+| **Group-add-admin** | Promotes one or more participants to group admins |
+| **Group-remove-admin** | Removes admin rights from one or more members |
+| **Group-metadata** | Returns group information (name, participants, admins, etc.) |
+
+New tools are added as the server evolves.
+
+<Warning>
+Actions on groups and participants take effect immediately on WhatsApp. As with any action performed by an AI, review what the agent is about to do before authorizing it, especially in automated flows.
+</Warning>
+
+---
+
+## How it works in practice
+
+```
+User makes a request to the AI
+        │
+        ▼
+AI queries the Z-API MCP → receives the list of available tools
+        │
+        ▼
+AI selects the tool and sends the parameters (e.g., number + message)
+        │
+        ▼
+MCP validates the OAuth token and triggers Z-API
+        │
+        ▼
+Action executed on WhatsApp → AI confirms to the user ✅
+```
+
+---
+
+## Frequently asked questions
+
+<AccordionGroup>
+  <Accordion title="Do I need a Z-API account?">
+    Yes. The MCP is a layer on top of Z-API, not a replacement. The WhatsApp instance still needs to be connected normally on the platform.
+  </Accordion>
+
+  <Accordion title="Which number does the message come from?">
+    From the number connected to the client's Z-API instance — the same as any message sent through the traditional API.
+  </Accordion>
+
+  <Accordion title="Can I create and manage groups through the MCP?">
+    Yes. It's already possible to create groups, add and remove participants, and promote or remove admins directly through the MCP tools.
+  </Accordion>
+</AccordionGroup>
diff --git a/images/claude-add-custom-connector.png b/images/claude-add-custom-connector.png
diff --git a/images/claude-adicionar-conector-personalizado.png b/images/claude-adicionar-conector-personalizado.png
diff --git a/images/claude-ativar-zapi-conversa.png b/images/claude-ativar-zapi-conversa.png
diff --git a/images/claude-conectado-retorno.png b/images/claude-conectado-retorno.png
diff --git a/images/claude-conectores-adicionar.png b/images/claude-conectores-adicionar.png
diff --git a/images/claude-connect-zapi.png b/images/claude-connect-zapi.png
diff --git a/images/claude-connected-return.png b/images/claude-connected-return.png
diff --git a/images/claude-connectors-add.png b/images/claude-connectors-add.png
diff --git a/images/claude-enable-zapi-conversation.png b/images/claude-enable-zapi-conversation.png
diff --git a/images/claude-selecionar-instancia.png b/images/claude-selecionar-instancia.png
diff --git a/images/claude-select-instance.png b/images/claude-select-instance.png
diff --git a/images/claude-vincular-zapi.png b/images/claude-vincular-zapi.png
diff --git a/mcp/how-to-connect.mdx b/mcp/how-to-connect.mdx
@@ -0,0 +1,105 @@
+---
+title: "Como conectar"
+description: "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="/images/claude-conectores-adicionar.png" alt="Tela de Conectores do Claude com o menu Adicionar aberto, mostrando as opções Navegar conectores e Adicionar conector personalizado" />
+</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="/images/claude-adicionar-conector-personalizado.png" 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"}}/>
+</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="/images/claude-vincular-zapi.png" alt="Página do conector Z-API no Claude mostrando o botão Vincular antes de conectar" />
+</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="/images/claude-selecionar-instancia.png" 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" />
+</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="/images/claude-conectado-retorno.png" alt="Tela de confirmação Conectado, indicando que o Claude será aberto de volta automaticamente" style={{borderRadius: "8px", maxWidth: "400px", width: "100%"}}/>
+</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="/images/claude-ativar-zapi-conversa.png" alt="Menu de conectores do Claude no campo de mensagem com o toggle da Z-API ativado" style={{borderRadius: "8px"}}/>
+</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>