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, 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 →

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

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:

{
  "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).

Abra Personalizar → Conectores, clique em + Adicionar, depois em Adicionar conector personalizado.
Dê um nome a ele e insira https://mcp.youraiconnector.com/mcp como a URL.
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”.
Em Cabeçalhos de solicitação, adicione um cabeçalho chamado X-API-Key com sua chave de API como valor.
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 18 ou superior:

{
  "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 Desktop, Cursor ou outro cliente MCP, ou a API do Claude.

O ChatGPT ainda pode ler a documentação de ajuda sem uma conexão: veja A documentação de ajuda está integrada 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:

{
  "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 lista o que é suportado.

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.

Clientes com limite de ferramentas

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 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.
“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.
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, 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 — gere ou altere a chave que esta conexão usa.
Webhooks — a contraparte baseada em push para esta conexão MCP baseada em pull.

Conectar Assistentes de IA (MCP) #

Claude Code #

Claude Desktop #

ChatGPT #

Cursor e outros clientes MCP #

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

O que você pode fazer #

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

Testando o agente de um cliente #

Clientes com limite de ferramentas #

Os documentos de ajuda são integrados #

Encontrando ou Gerando Sua Chave de API #

Solução de problemas #

Próximos passos #