diff --git a/docs.json b/docs.json
index c97a22d..4eecfcc 100644
--- 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
new file mode 100644
index 0000000..cc5516a
--- /dev/null
+++ 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**.
+
+
+ 
+
+
+### 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`
+
+
+ 
+
+
+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**.
+
+
+ 
+
+
+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**.
+
+
+ 
+
+
+
+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.
+
+
+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.
+
+
+ 
+
+
+### 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.
+
+
+ 
+
+
+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.
+
+
+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.
+
+
+---
+
+## 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.
+
+
+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.
+
+
+---
+
+## Frequently asked questions
+
+
+
+ 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.
+
+
+
+ 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.
+
+
+
+ **(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.
+
+
+
+ No. Once added and linked, the connector remains available to be enabled in any new conversation through the connectors menu.
+
+
\ No newline at end of file
diff --git a/en/mcp/introduction.mdx b/en/mcp/introduction.mdx
new file mode 100644
index 0000000..3c6a3ef
--- /dev/null
+++ 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.
+
+
+**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.
+
+
+---
+
+## 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.
+
+
+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.
+
+
+---
+
+## 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
+
+
+
+ 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.
+
+
+
+ From the number connected to the client's Z-API instance — the same as any message sent through the traditional API.
+
+
+
+ Yes. It's already possible to create groups, add and remove participants, and promote or remove admins directly through the MCP tools.
+
+
\ No newline at end of file
diff --git a/images/claude-add-custom-connector.png b/images/claude-add-custom-connector.png
new file mode 100644
index 0000000..48897d1
Binary files /dev/null and b/images/claude-add-custom-connector.png differ
diff --git a/images/claude-adicionar-conector-personalizado.png b/images/claude-adicionar-conector-personalizado.png
new file mode 100644
index 0000000..f82ebaf
Binary files /dev/null and b/images/claude-adicionar-conector-personalizado.png differ
diff --git a/images/claude-ativar-zapi-conversa.png b/images/claude-ativar-zapi-conversa.png
new file mode 100644
index 0000000..4aea659
Binary files /dev/null and b/images/claude-ativar-zapi-conversa.png differ
diff --git a/images/claude-conectado-retorno.png b/images/claude-conectado-retorno.png
new file mode 100644
index 0000000..ae80120
Binary files /dev/null and b/images/claude-conectado-retorno.png differ
diff --git a/images/claude-conectores-adicionar.png b/images/claude-conectores-adicionar.png
new file mode 100644
index 0000000..0b853b4
Binary files /dev/null and b/images/claude-conectores-adicionar.png differ
diff --git a/images/claude-connect-zapi.png b/images/claude-connect-zapi.png
new file mode 100644
index 0000000..fb8c00d
Binary files /dev/null and b/images/claude-connect-zapi.png differ
diff --git a/images/claude-connected-return.png b/images/claude-connected-return.png
new file mode 100644
index 0000000..0bdc0da
Binary files /dev/null and b/images/claude-connected-return.png differ
diff --git a/images/claude-connectors-add.png b/images/claude-connectors-add.png
new file mode 100644
index 0000000..873e0f4
Binary files /dev/null and b/images/claude-connectors-add.png differ
diff --git a/images/claude-enable-zapi-conversation.png b/images/claude-enable-zapi-conversation.png
new file mode 100644
index 0000000..08c6654
Binary files /dev/null and b/images/claude-enable-zapi-conversation.png differ
diff --git a/images/claude-selecionar-instancia.png b/images/claude-selecionar-instancia.png
new file mode 100644
index 0000000..cfcd788
Binary files /dev/null and b/images/claude-selecionar-instancia.png differ
diff --git a/images/claude-select-instance.png b/images/claude-select-instance.png
new file mode 100644
index 0000000..040cd1c
Binary files /dev/null and b/images/claude-select-instance.png differ
diff --git a/images/claude-vincular-zapi.png b/images/claude-vincular-zapi.png
new file mode 100644
index 0000000..7abb0cc
Binary files /dev/null and b/images/claude-vincular-zapi.png differ
diff --git a/mcp/how-to-connect.mdx b/mcp/how-to-connect.mdx
new file mode 100644
index 0000000..b785537
--- /dev/null
+++ 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**.
+
+
+ 
+
+
+### 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`
+
+
+ 
+
+
+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**.
+
+
+ 
+
+
+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**.
+
+
+ 
+
+
+
+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.
+
+
+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.
+
+
+ 
+
+
+### 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**.
+
+
+ 
+
+
+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ê.
+
+
+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.
+
+
+---
+
+## 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.
+
+
+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.
+
+
+---
+
+## Perguntas frequentes
+
+
+
+ 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.
+
+
+
+ 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.
+
+
+
+ **(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.
+
+
+
+ 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.
+
+
\ No newline at end of file
diff --git a/mcp/introduction.mdx b/mcp/introduction.mdx
new file mode 100644
index 0000000..34314e3
--- /dev/null
+++ b/mcp/introduction.mdx
@@ -0,0 +1,83 @@
+---
+title: "Introdução"
+description: "Conecte sua IA ao WhatsApp usando o servidor MCP da Z-API"
+---
+
+## O que é o MCP Z-API?
+
+O MCP Z-API é um servidor que expõe operações do WhatsApp como ferramentas prontas para qualquer IA compatível com MCP — Claude, ChatGPT, agentes customizados, entre outros.
+
+Em vez de chamar a API REST diretamente, a IA conversa com o servidor MCP e ele executa as ações na sua instância Z-API.
+
+
+**Novo no MCP?** MCP (Model Context Protocol) é um padrão aberto que define como IAs se conectam a sistemas externos. Funciona como um "menu de habilidades": a IA pergunta o que o servidor sabe fazer, escolhe a ação e envia os dados necessários.
+
+
+---
+
+## O que dá pra fazer
+
+Hoje o MCP Z-API expõe 9 ferramentas, divididas em dois grupos:
+
+### Mensagens
+
+| Ferramenta | O que faz |
+|---|---|
+| **Send-text** | Envia uma mensagem de texto para um número ou grupo |
+| **Send-image** | Envia uma imagem (link ou Base64), com legenda opcional |
+| **Send-video** | Envia um vídeo (link ou Base64), com legenda opcional |
+
+### Grupos
+
+| Ferramenta | O que faz |
+|---|---|
+| **Group-create** | Cria um novo grupo com os participantes informados |
+| **Group-add-participant** | Adiciona novos membros a um grupo existente |
+| **Group-remove-participant** | Remove membros de um grupo |
+| **Group-add-admin** | Promove um ou mais participantes a administradores do grupo |
+| **Group-remove-admin** | Remove a administração de um ou mais membros do grupo |
+| **Group-metadata** | Retorna as informações do grupo (nome, participantes, admins, etc.) |
+
+Novas ferramentas são adicionadas conforme o servidor evolui.
+
+
+Ações sobre grupos e participantes têm efeito imediato no WhatsApp. Como qualquer ação executada por uma IA, revise o que o agente vai fazer antes de autorizar, principalmente em fluxos automatizados.
+
+
+---
+
+## Como funciona na prática
+
+```
+Usuário faz um pedido à IA
+ │
+ ▼
+IA consulta o MCP Z-API → recebe a lista de ferramentas disponíveis
+ │
+ ▼
+IA escolhe a ferramenta e envia os parâmetros (ex.: número + mensagem)
+ │
+ ▼
+MCP valida o token OAuth e aciona a Z-API
+ │
+ ▼
+Ação executada no WhatsApp → IA confirma ao usuário ✅
+```
+
+---
+
+## Perguntas frequentes
+
+
+
+ Sim. O MCP é uma camada sobre a Z-API, não um substituto. A instância de WhatsApp precisa estar conectada normalmente na plataforma.
+
+
+
+ Do número conectado à instância Z-API do cliente — igual a qualquer envio pela API tradicional.
+
+
+
+ Sim. Hoje já é possível criar grupos, adicionar e remover participantes, e promover ou remover administradores diretamente pelas ferramentas do MCP.
+
+
\ No newline at end of file