# Conectar Assistentes de IA (MCP) Your AI Connector disponibiliza um **servidor MCP** oficial — um endpoint do Model Context Protocol que permite que assistentes de IA como **Claude Code**, **Claude Desktop**, **Cursor** e seus próprios aplicativos controlem sua conta Your AI Connector diretamente. Pergunte em linguagem simples ("liste meus agentes de IA", "adicione este lead", "quanto a IA me custou esta semana?") e o assistente chamará a API do Your AI Connector para você. É a mesma API v1 que você acessa com uma [chave de API](api-access.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, funções personalizadas, base de conhecimento, agendamentos, análises, tags, listas, transmissões, negócios, conexões de canal e subcontas. As automações podem ser listadas e lidas, mas ainda não criadas ou editadas via MCP; crie-as no aplicativo. 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 Your AI Connector (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) > 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 ai-connector 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 **ai-connector ✓ connected**. 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": { "ai-connector": { "type": "http", "url": "https://mcp.youraiconnector.com/mcp", "headers": { "X-API-Key": "YOUR_API_KEY" } } } } ``` ## Claude Desktop Adicione o servidor como um conector personalizado. Ele é configurado na sua conta Claude, portanto funciona tanto no Claude Desktop quanto no claude.ai (contas Claude gratuitas podem adicionar um conector personalizado). 1. Abra **Personalizar → Conectores**, clique em **+ Adicionar**, depois em **Adicionar conector personalizado**. 2. Dê um nome a ele e insira `https://mcp.youraiconnector.com/mcp` como a URL. 3. Em **Autenticação**, escolha **Sem login**. O servidor MCP não possui uma página de login: escolher uma opção de login resulta em "Não foi possível registrar com o serviço de login". 4. Em **Cabeçalhos de solicitação**, adicione um cabeçalho chamado `X-API-Key` com sua chave de API como valor. 5. Clique em **Adicionar**. As ferramentas Your AI Connector aparecerão no menu de ferramentas de um novo chat. **Não há campo de Cabeçalhos de solicitação?** Sua versão do Claude Desktop está desatualizada: atualize-a ou use o arquivo de configuração. O arquivo de configuração (`claude_desktop_config.json`, Configurações → Desenvolvedor → Editar Configuração) apenas executa programas no seu computador e ignora uma entrada `url`, portanto, ele precisa da pequena ponte `mcp-remote`, que requer [Node.js](https://nodejs.org) 18 ou superior: ```json { "mcpServers": { "ai-connector": { "command": "npx", "args": [ "-y", "mcp-remote", "https://mcp.youraiconnector.com/mcp", "--header", "X-API-Key:${AI_CONNECTOR_KEY}" ], "env": { "AI_CONNECTOR_KEY": "YOUR_API_KEY" } } } } ``` Mantenha `X-API-Key:${AI_CONNECTOR_KEY}` exatamente como escrito, sem espaço após os dois-pontos (no Windows, um espaço separa o cabeçalho), e coloque sua chave apenas em `env`. Em seguida, encerre completamente o Claude Desktop (no Windows, clique com o botão direito no ícone da bandeja → Sair) e abra-o novamente. ## ChatGPT O ChatGPT não consegue se conectar ao servidor MCP no momento. Seu formulário de conector personalizado oferece apenas **OAuth** ou **Sem autenticação**, e o servidor MCP do Your AI Connector faz login com sua chave de API, enviada como um cabeçalho de solicitação. Escolher OAuth falha com "não foi possível descobrir as configurações de OAuth", e Sem autenticação é recusado porque cada solicitação precisa da chave. Use um assistente que permita definir um cabeçalho de solicitação: [Claude Code](#claude-code), [Claude Desktop](#claude-desktop), [Cursor ou outro cliente MCP](#cursor--other-mcp-clients), ou [a API do Claude](#the-claude-api-build-it-into-your-own-app). O ChatGPT ainda pode ler a documentação de ajuda sem uma conexão: veja [A documentação de ajuda está integrada](#the-help-docs-are-built-in) para os arquivos `llms.txt` públicos. ## 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 `ai-connector` 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 Your AI Connector sem um cliente separado: ```json { "model": "claude-opus-4-8", "messages": [{ "role": "user", "content": "List my AI agents" }], "mcp_servers": [ { "type": "url", "name": "ai-connector", "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: - **Agentes de IA:** listar, criar, atualizar, pausar/retomar, inspecionar configuração. - **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 possui?" - "Quanto a IA custou para cada um dos meus clientes esta semana?" - "Qual é o estado dos canais da Northside Dental e quantos chats foram recebidos esta semana?" 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** funciona da mesma maneira. Toda ação que aceita uma conta de cliente na API está disponível para um cliente nomeado: configurar agentes de IA, base de conhecimento, funções personalizadas, modelos de WhatsApp, pontos de entrada, conexões de canal, contatos, etiquetas, transmissões, agendamentos, negócios e tarefas, e envio de mensagens. As exceções são as ações de nível de agência, que sempre são executadas na sua própria conta de agência: gerenciar as contas dos clientes (limites, recursos, preços, pausa), snapshots, sua equipe e chaves de API. Adicionar ou remover contatos da lista de um cliente ainda não está disponível para um cliente nomeado; faça isso a partir da chave do próprio cliente ou na conta dele. O [guia da API de agência](../agency/api-for-agencies.md#where-sub_account_id-is-supported) lista o que é suportado. ::: neutral-mcp As ferramentas de agência estão apenas no endereço padrão, sem marca, `https://mcp.youraiconnector.com/mcp`. Um endereço MCP white-label no seu próprio domínio (`mcp.youragency.com`) é criado para seus clientes e não as inclui, portanto, conecte-se com o endereço padrão, sem marca, ao gerenciar contas de clientes. ::: 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. ### Testando o agente de um cliente Peça ao assistente para testar o agente de um cliente ("envie 'vocês entregam aos domingos?' para o agente da Padaria do cliente X e me mostre o que ele fez"). Ele envia uma mensagem de Teste com sua chave de agência e o `sub_account_id` do cliente, aguarda e lê a resposta, além de quaisquer ações que o agente tenha realizado. Nenhuma cópia do agente é necessária. Se o assistente disser que você não possui uma conta de agência, ele está conectado com a chave de um cliente: reconecte-o com a chave da sua conta de agência. Veja [Testar](../chats/playground.md#testing-an-agent-from-the-api-or-an-ai-assistant). ## Clientes com limite de ferramentas ::: neutral-mcp Alguns clientes de IA aceitam apenas um servidor com um número limitado de ferramentas. O Composio, por exemplo, recusa um servidor que liste mais de 500 ferramentas e não importa nenhuma delas. A conexão completa da agência lista mais do que isso, portanto, adicione `?tags=` ao endereço apenas com os grupos de ferramentas de que você precisa. Para uma agência que deseja listar as contas de seus clientes, ler seus contatos, chats e mensagens, e enviar mensagens: ``` https://mcp.youraiconnector.com/mcp?tags=SubAccounts,Contacts,Messages ``` Isso carrega cerca de 80 ferramentas. Nomeie o cliente em sua solicitação e o assistente agirá na conta desse cliente, conforme descrito acima. - Separe os grupos com vírgulas; letras maiúsculas ou minúsculas funcionam. - Para adicionar ferramentas individuais, liste seus nomes exatos com `tools=`, por exemplo `?tags=Contacts&tools=list_or_get_subaccounts`. Você obtém todas as ferramentas de ambas as listas. - As ferramentas de documentação de ajuda estão sempre incluídas. - A chave de API ainda vai no cabeçalho `X-API-Key` (ou `Authorization: Bearer YOUR_API_KEY`), nunca no endereço. ::: ## Os documentos de ajuda são integrados O servidor MCP fornece ao assistente sua **conta** e esta **documentação**. Três ferramentas leem os documentos de ajuda em tempo real, para que o assistente possa pesquisar como um recurso funciona ou o que mudou recentemente, em vez de adivinhar: - `docs_search`: encontra as seções que respondem a uma pergunta e as retorna com o link da página. - `docs_read`: lê uma página inteira ou uma seção dela. - `docs_list`: lista todas as páginas por área. Não há nada para configurar, e as ferramentas de documentos nunca acessam os dados da sua conta. Pergunte "como funcionam os pontos de entrada?" ou "o que há de novo nas automações?" e o assistente pesquisará nos documentos primeiro. Como as ferramentas leem o próprio site de ajuda, um recurso é conhecido pelo seu assistente assim que seu guia é publicado. Um assistente que não está conectado via MCP ainda pode ler os documentos: aponte-o para `https://docs.youraiconnector.com/llms.txt` (um índice de cada página de ajuda com um link para a versão Markdown de cada página) ou `https://docs.youraiconnector.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. ## 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 - **"Conexão recusada" ou "não encontrado"** — 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 o servidor novamente com um `X-API-Key` válido. - **"Não foi possível descobrir as configurações de OAuth" (ChatGPT)** — o ChatGPT suporta apenas OAuth ou nenhuma autenticação para conectores personalizados, e o servidor MCP usa uma chave de API, portanto, o ChatGPT não pode se conectar por enquanto. Veja [ChatGPT](#chatgpt). - **"Não foi possível registrar com o serviço de login" ou "adicione um ID de Cliente OAuth" (Claude Desktop)** — o conector personalizado foi adicionado com uma opção de login. Não há ID de cliente OAuth para inserir: remova o conector e adicione-o novamente com **Autenticação → Sem login** e sua chave de API como um cabeçalho de solicitação `X-API-Key`, conforme em [Claude Desktop](#claude-desktop). - **O Claude Desktop não mostra ferramentas após editar o arquivo de configuração** — o arquivo de configuração ignora uma entrada `"url"`; use o conector personalizado ou o formulário `mcp-remote` em [Claude Desktop](#claude-desktop), e encerre completamente e reabra o aplicativo. - **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 ao vivo 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 servir 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. O endereço com marca deixa de fora as ferramentas da agência; continue usando o endereço padrão sem marca para elas. Até que seu endereço com marca seja verificado, use o endereço padrão sem marca: é 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.