# Conectar Assistentes de IA (MCP)

<span data-t="appName">DM Champ</span> disponibiliza um **servidor MCP** oficial — um endpoint do Model Context Protocol
que permite que assistentes de IA como **Claude Code**, **Claude Desktop**, **ChatGPT**,
**Cursor** e seus próprios aplicativos controlem sua conta <span data-t="appName">DM Champ</span> diretamente. Pergunte em linguagem simples
("liste minhas campanhas ativas", "adicione este lead", "quanto a IA me custou esta semana?")
e o assistente chama a API do <span data-t="appName">DM Champ</span> para você.

É a mesma API v1 documentada na [seção de API](../api/getting-started.md), autenticada com sua própria chave de API. O servidor MCP cria uma ferramenta para cada operação em nossa especificação de API publicada, portanto, ele cobre a maior parte, mas não toda, a API v1: contatos, mensagens, campanhas, agentes de IA, base de conhecimento, agendamentos, análises, tags, listas e subcontas. Transmissões, Automações e Negócios ainda não estão disponíveis como ferramentas MCP — use a API REST diretamente para esses casos. Dentro do que é exposto, não há permissões por ferramenta nem padrão de somente leitura, portanto, a chave de API é todo o controle de acesso.

- **Endpoint:** `https://mcp.youraiconnector.com/mcp`
- **Autenticação:** sua chave de API do <span data-t="appName">DM Champ</span> (enviada como o cabeçalho `X-API-Key`)
- **Requisitos:** um plano com acesso à API. [Crie uma chave de API →](api-access.md#generating-your-api-key)

> Sua chave de API atua em **sua própria conta**, com as mesmas permissões que o restante da API — e pode ler as contas de clientes que você gerencia, se estiver em um plano de agência (veja abaixo). Trate-a como uma senha. Você pode revogá-la a qualquer momento em Configurações → Integrações → Chave de API, o que corta instantaneamente o acesso do assistente.

## Claude Code

```bash
claude mcp add --transport http dm-champ https://mcp.youraiconnector.com/mcp \
  --header "X-API-Key: YOUR_API_KEY"
```

Em seguida, execute `/mcp` dentro do Claude Code para confirmar que ele mostra **dm-champ ✓ conectado**.

Por padrão, o servidor é adicionado no escopo **local** (apenas você, este projeto).
Use `--scope user` para torná-lo disponível em todos os seus projetos, ou `--scope
project` to commit it to a repo's `.mcp.json` para sua equipe:

```json
{
  "mcpServers": {
    "dm-champ": {
      "type": "http",
      "url": "https://mcp.youraiconnector.com/mcp",
      "headers": { "X-API-Key": "YOUR_API_KEY" }
    }
  }
}
```

## Claude Desktop

Edite seu `claude_desktop_config.json` (Configurações → Desenvolvedor → Editar Configuração) e
adicione:

```json
{
  "mcpServers": {
    "dm-champ": {
      "type": "http",
      "url": "https://mcp.youraiconnector.com/mcp",
      "headers": { "X-API-Key": "YOUR_API_KEY" }
    }
  }
}
```

Reinicie o Claude Desktop. As ferramentas do <span data-t="appName">DM Champ</span> aparecerão no menu de ferramentas.

## ChatGPT

Conectores MCP personalizados estão disponíveis no ChatGPT Business, Enterprise e Pro. Um
proprietário ou administrador do workspace precisa ativar o **modo de desenvolvedor / conectores personalizados**
nas configurações do workspace primeiro — sem isso, a opção de criar um conector
nunca aparece.

Em seguida, crie o conector com:

- **URL:** `https://mcp.youraiconnector.com/mcp`
- **Autenticação:** Cabeçalhos personalizados
- **Nome do cabeçalho:** `X-API-Key`
- **Valor do cabeçalho:** sua chave de API do <span data-t="appName">DM Champ</span>

A URL deve terminar em `/mcp`. Colar apenas `https://mcp.youraiconnector.com` é o erro
mais comum — o ChatGPT verifica esse endereço exato, não encontra nada lá e
exibe **"Unable to add connector URL"**.

## Cursor e outros clientes MCP

A maioria dos editores compatíveis com MCP usa o mesmo formato `.mcp.json` mostrado acima (um servidor HTTP
com um `url` e um cabeçalho `X-API-Key`). Adicione um servidor `dm-champ` apontando
para `https://mcp.youraiconnector.com/mcp` e cole sua chave de API no cabeçalho.

## A API do Claude (integre ao seu próprio aplicativo)

Você pode conectar o servidor MCP programaticamente com o conector MCP da API do Claude, para que um agente que você criar possa usar as ferramentas do <span data-t="appName">DM Champ</span> sem um cliente separado:

```json
{
  "model": "claude-opus-4-8",
  "messages": [{ "role": "user", "content": "List my live campaigns" }],
  "mcp_servers": [
    {
      "type": "url",
      "name": "dm-champ",
      "url": "https://mcp.youraiconnector.com/mcp",
      "authorization_token": "YOUR_API_KEY"
    }
  ]
}
```

## O que você pode fazer

Dentro da parte da API v1 que o servidor MCP expõe, o assistente escolhe a ferramenta certa automaticamente:

- **Campanhas:** listar, criar, atualizar, pausar/retomar, inspecionar configuração do bot.
- **Contatos:** pesquisar, criar, marcar, adicionar a listas, importar.
- **Base de conhecimento / FAQs:** adicionar, editar, importar em massa, aprovar sugestões de IA.
- **Mensagens:** ler conversas, enviar uma mensagem para um contato.
- **Agendamentos:** listar, reservar, cancelar.
- **Tarefas:** criar, concluir, listar.
- **Análises:** estatísticas de mensagens, uso de créditos, custo de IA.
- **Canais:** verificar status da conexão, iniciar um fluxo de conexão.

## Perguntando sobre as contas de seus clientes (agências)

Uma única conexão cobre todas as contas que você gerencia. Você não precisa adicionar uma segunda conexão por cliente: em um plano de agência, o assistente pode ler qualquer conta de cliente sob sua gestão, para que você possa perguntar sobre todas elas em uma única conversa.

Basta nomear o cliente:

- "Quantos contatos o Bella's Bistro tem?"
- "Quanto a IA custou para cada um dos meus clientes esta semana?"
- "Quais campanhas estão ativas para a Northside Dental e qual é o estado dos canais deles?"

Isso abrange a leitura de contatos, mensagens, chats, campanhas, agendamentos, tarefas, tags, eventos, FAQs, fontes da base de conhecimento, números de telefone, canais, webhooks e análises. Verificamos se a conta é realmente sua antes que qualquer coisa seja executada — solicitar uma que não seja retornará como "não encontrada". Se você não especificar o cliente, o assistente lerá sua própria conta, exatamente como antes.

**Alterar a conta de um cliente** é mais limitado. Configurar agentes de IA, funções
personalizadas, modelos de WhatsApp, pontos de entrada, conexões de canal, status de campanha e
comprar um número funcionam para um cliente nomeado; a maioria das outras ações de escrita ainda é executada na sua
própria conta, portanto, faça isso a partir da chave do próprio cliente ou da
[REST API](../agency/api-for-agencies.md), que abrange mais recursos.

Esta também é a resposta para um cliente que gerencia **vários negócios sob um único login**. Dê a cada negócio sua própria conta e, em seguida, convide o e-mail do cliente como membro da equipe em todas elas: eles fazem login uma vez e alternam entre suas marcas com o seletor de conta na barra lateral.

## Fornecendo os documentos de ajuda ao seu assistente

O servidor MCP fornece ao assistente a sua **conta**; ele não fornece esta documentação. Se você também quiser que ele responda corretamente a perguntas do tipo "como eu faço...", aponte-o para `https://docs.dmchamp.com/llms.txt` (um índice de todas as páginas de ajuda com um link para a versão Markdown de cada página) ou `https://docs.dmchamp.com/llms-full.txt` (toda a documentação em um único arquivo Markdown). Ambos são públicos, não precisam de chave e são reconstruídos a cada alteração na documentação. Veja [Lendo estes documentos como Markdown](../api/getting-started.md#reading-these-docs-as-markdown).

## Encontrando ou Gerando Sua Chave de API

A chave de API que esta conexão usa fica em **Configurações → Integrações → Chave de API** — sua própria seção, separada dos Webhooks. Consulte [Acesso à API](api-access.md#generating-your-api-key) para ver os passos exatos.

## Solução de problemas

- **"Unable to add connector URL" (ChatGPT) / "connection refused"** — o
  endereço está sem o `/mcp` no final. Use
  `https://mcp.youraiconnector.com/mcp`, não `https://mcp.youraiconnector.com`.
- **`Needs authentication` / 401** — sua chave de API está faltando ou incorreta. Adicione
  novamente o servidor com uma `X-API-Key` válida.
- **Uma ferramenta retorna `403`** — seu plano ou função na equipe não permite essa ação;
  o servidor MCP não impõe nada extra, é a mesma verificação de permissão da
  API.
- **Ferramenta não encontrada** — a lista de ferramentas é gerada em tempo real a partir da API, portanto,
  ela sempre corresponde à versão atual; reconecte para atualizar.
- **Um aviso de segurança ou certificado em seu próprio domínio** — apontar um registro
  DNS para nós não é suficiente por si só: o subdomínio também precisa ser verificado
  no painel antes que possa oferecer uma conexão segura. Agências de white-label
  podem colocar o endereço MCP em seu próprio domínio (por exemplo,
  `mcp.youragency.com`) a partir do cartão **Domínio personalizado** em **Configurações →
  White Labeling** — adicione o CNAME no seu registrador primeiro, depois insira o
  nome do host no bloco **Domínio MCP (assistentes de IA)** e clique em **Verificar**,
  o mesmo fluxo dos seus outros subdomínios de marca. Até que seja verificado, use o endereço padrão acima — ele não
  possui marca, portanto, é seguro compartilhar com clientes.

---

## Próximos passos

- [Acesso à API](api-access.md) — gere ou altere a chave que esta conexão usa.
- [Webhooks](webhooks.md) — a contraparte baseada em push para esta conexão MCP baseada em pull.