# Ligar Assistentes de IA (MCP)

<span data-t="appName">DM Champ</span> disponibiliza um **servidor MCP** oficial — um endpoint do Model Context Protocol
que permite a assistentes de IA como o **Claude Code**, **Claude Desktop**, **ChatGPT**,
**Cursor** e as suas próprias aplicações controlarem diretamente a sua conta <span data-t="appName">DM Champ</span>. Peça em linguagem simples
("lista as minhas campanhas ativas", "adiciona este lead", "quanto é que a IA me custou esta semana?")
e o assistente chama a API <span data-t="appName">DM Champ</span> por si.

É a mesma API v1 documentada na [secção da API](../api/getting-started.md), autenticada
com a sua própria chave de API. O servidor MCP cria uma ferramenta para cada operação na nossa
especificação de API publicada, pelo que abrange a maior parte, mas não toda, a API v1: contactos, mensagens, campanhas,
agentes de IA, base de conhecimento, marcações, análises, etiquetas, listas e subcontas. As transmissões,
automatizações e negócios ainda não estão disponíveis como ferramentas MCP — utilize a API REST diretamente para esses fins.
Dentro do que é exposto, não existem permissões por ferramenta nem predefinições de leitura, pelo que a chave de API é o controlo de acesso total.

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

> A sua chave de API atua na **sua própria conta**, com as mesmas permissões que o
> resto da API — e pode ler as contas de cliente que gere, se estiver num
> plano de agência (ver abaixo). Trate-a como uma palavra-passe. Pode revogá-la a qualquer momento em
> Definiçõ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"
```

Depois, execute `/mcp` dentro do Claude Code para confirmar que aparece **dm-champ ✓ ligado**.

Por predefinição, o servidor é adicionado no âmbito **local** (apenas para si, neste projeto).
Use `--scope user` para o tornar disponível em todos os seus projetos, ou `--scope
project` to commit it to a repo's `.mcp.json` para a sua equipa:

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

## Claude Desktop

Edite o seu `claude_desktop_config.json` (Definições → Programador → 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 <span data-t="appName">DM Champ</span> aparecerão no menu de ferramentas.

## ChatGPT

Os conectores MCP personalizados estão disponíveis no ChatGPT Business, Enterprise e Pro. Um
proprietário ou administrador do espaço de trabalho tem de ativar o **modo de programador / conectores personalizados**
nas definições do espaço de trabalho primeiro — sem isso, a opção para criar um conector
nunca aparece.

Depois, 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:** a sua chave de API <span data-t="appName">DM Champ</span>

O URL tem de 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
apresenta **"Unable to add connector URL"**.

## Cursor e outros clientes MCP

A maioria dos editores compatíveis com MCP utiliza a mesma estrutura `.mcp.json` mostrada acima (um servidor HTTP
com um `url` e um cabeçalho `X-API-Key`). Adicione um servidor `dm-champ` a apontar
para `https://mcp.youraiconnector.com/mcp` e cole a sua chave de API no cabeçalho.

## A API do Claude (integre-a na sua própria aplicação)

Pode ligar o servidor MCP programaticamente com o conector MCP da API do Claude, para que um agente que crie possa utilizar as ferramentas <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 pode fazer

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

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

## Perguntar sobre as contas dos seus clientes (agências)

Uma ligação abrange todas as contas que gere. Não precisa de adicionar uma segunda ligação
por cliente: num plano de agência, o assistente pode ler qualquer conta de cliente sob a sua gestão,
pelo que pode perguntar sobre todas elas numa única conversa.

Basta indicar o nome do cliente:

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

Isto abrange a leitura de contactos, mensagens, chats, campanhas, marcações, tarefas, etiquetas,
eventos, FAQs, fontes da base de conhecimento, números de telefone, canais, webhooks e análises.
Verificamos se a conta é realmente sua antes de qualquer execução — pedir uma conta que não é sua
resulta em "não encontrada". Se não especificar o cliente, o assistente lê a 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, ligações de canais, estado de campanhas e comprar um número funcionam para um cliente nomeado; a maioria das outras ações de escrita ainda são executadas na sua própria conta, por isso faça-as a partir da chave desse cliente ou da [REST API](../agency/api-for-agencies.md), que abrange mais opções.

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

## Fornecer ao seu assistente a documentação de ajuda

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

## Encontrar ou Gerar a Sua Chave de API

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

## Resolução de Problemas

- **"Unable to add connector URL" (ChatGPT) / "connection refused"** — ao
  endereço falta o `/mcp` no final. Utilize
  `https://mcp.youraiconnector.com/mcp`, não `https://mcp.youraiconnector.com`.
- **`Needs authentication` / 401** — a sua chave de API está em falta ou incorreta. Adicione
  novamente o servidor com uma `X-API-Key` válida.
- **Uma ferramenta devolve `403`** — o seu plano ou função de equipa não permite essa ação;
  o servidor MCP não impõe nada extra, é a mesma verificação de permissões que a
  API.
- **Ferramenta não encontrada** — a lista de ferramentas é gerada em tempo real a partir da API, pelo que
  corresponde sempre à versão atual; volte a ligar para atualizar.
- **Um aviso de segurança ou de certificado no seu próprio domínio** — apontar um registo
  DNS para nós não é suficiente por si só: o subdomínio também tem de ser verificado
  no painel de controlo antes de poder servir uma ligação segura. As agências de
  white-label podem colocar o endereço MCP no seu próprio domínio (por exemplo,
  `mcp.youragency.com`) a partir do cartão **Domínio personalizado** em **Definições →
  White Labeling** — adicione primeiro o CNAME no seu registador, depois introduza
  o nome de anfitrião no bloco **Domínio MCP (assistentes de IA)** e clique em **Verificar**,
  o mesmo fluxo que os seus outros subdomínios de marca. Até ser verificado, utilize o endereço padrão acima — não tem marca,
  pelo que é seguro partilhar com clientes.

---

## Próximos Passos

- [Acesso à API](api-access.md) — gere ou renove a chave que esta ligação utiliza.
- [Webhooks](webhooks.md) — a contraparte baseada em push desta ligação MCP baseada em pull.