---
title: "Servidor MCP"
slug: mcp
group: "Primeiros passos"
source: https://linkzap.ia.br/developers/mcp
openapi: https://linkzap.ia.br/openapi.json
---

# Servidor MCP

A API inteira como ferramentas MCP: o Claude, o ChatGPT, o Cursor ou o seu agente operam a conta pela chave da API ou por login.

## Endereço e chave

O servidor fala MCP por HTTP (Streamable HTTP) em `https://linkzap.ia.br/mcp`, sem sessão. Ele se autentica como a API: `Authorization: Bearer lz_…`, com a chave de Configurações → Integrações (ou a de um canal, que limita ao número dele).

Comando — Claude Code:

```bash
claude mcp add --transport http linkzap https://linkzap.ia.br/mcp --header "Authorization: Bearer lz_SUA_CHAVE"
```

Configuração — Cursor, Claude Desktop e clientes com mcp.json:

```json
{
  "mcpServers": {
    "linkzap": {
      "url": "https://linkzap.ia.br/mcp",
      "headers": {
        "Authorization": "Bearer lz_SUA_CHAVE"
      }
    }
  }
}
```

## Por login (OAuth), sem chave

Os conectores do claude.ai e do ChatGPT entram por login: adicione `https://linkzap.ia.br/mcp` como conector personalizado, entre com a sua conta do LinkZap e escolha a organização. Só autoriza quem pode gerenciar as integrações dela. O servidor anuncia tudo pelos metadados padrão (`/.well-known/oauth-protected-resource/mcp`), com registro dinâmico de cliente e PKCE.

- O acesso é conferido a cada chamada: quem autorizou tem de seguir na organização e com a permissão de integrações.
- **Revogar** fica em Configurações → Integrações → Aplicativos conectados, e vale na chamada seguinte.
- O mesmo token também serve à API v1.

## As ferramentas

Cada operação da API v1 é uma ferramenta, com o `operationId` como nome. Os parâmetros de caminho, de consulta e os campos do corpo entram lado a lado. A resposta é o JSON que a rota devolveria, e uma recusa (422, 403, 404) volta como erro da ferramenta, com a mesma mensagem.

- `getMe` — Confere a chave (leitura)
- `listChannels` — Lista os números conectados (leitura)
- `listContacts` — Lista e busca contatos (leitura)
- `upsertContact` — Cria ou atualiza um contato
- `listConversations` — Lista conversas (leitura)
- `listMessages` — Lê o histórico de uma conversa (leitura)
- `sendMessage` — Envia uma mensagem
- `listFlows` — Lista os fluxos (leitura)
- `startFlow` — Inicia um fluxo para um telefone
- `listPipelines` — Lista os funis e as etapas (leitura)
- `listDeals` — Lista negócios (leitura)
- `createDeal` — Cria um negócio
- `updateDeal` — Muda um negócio: dados, etapa ou estado
- `listTasks` — Lista tarefas (leitura)
- `createTask` — Cria uma tarefa
- `updateTask` — Conclui, reabre ou edita uma tarefa
- `listActions` — Lista as ações (leitura)
- `describeAction` — Descreve uma ação (leitura)
- `runAction` — Executa uma ação

> [!WARNING]
> **A chave da conta pode tudo o que a API pode**
>
> Inclusive enviar mensagem, mudar negócio e começar fluxo. Para um assistente que só deve ler ou só deve falar por um número, entregue uma chave de canal e revogue quando não precisar mais. O freio por chave e por organização é o da API.