Ligar 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 o Claude Code, Claude Desktop, Cursor e as suas próprias aplicações controlem a sua conta Your AI Connector diretamente. Peça em linguagem simples (“lista os meus agentes de IA”, “adiciona este lead”, “quanto me custou a IA esta semana?”) e o assistente chama a API Your AI Connector por si.

É a mesma API v1 a que acede com uma chave de API, 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 a totalidade, da API v1: contactos, mensagens, campanhas, agentes de IA, funções personalizadas, base de conhecimento, marcações, análises, etiquetas, listas, transmissões, negócios, ligações de canais e subcontas. As automatizações podem ser listadas e lidas, mas ainda não podem ser criadas ou editadas através do MCP; crie-as na aplicação. Dentro do que é exposto, não existem permissões por ferramenta nem predefinições de apenas leitura, pelo que a chave de API é todo o controlo de acesso.

Endpoint: https://mcp.youraiconnector.com/mcp
Autenticação: a 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 →

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

claude mcp add --transport http ai-connector https://mcp.youraiconnector.com/mcp \
  --header "X-API-Key: YOUR_API_KEY"

Depois, execute /mcp no Claude Code para confirmar que aparece ai-connector ✓ connected.

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:

{
  "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. Este é configurado na sua conta Claude, pelo que funciona tanto no Claude Desktop como em claude.ai (as contas Claude gratuitas podem adicionar um conector personalizado).

Abra Customize → Connectors, clique em + Add e, depois, em Add custom connector.
Dê-lhe um nome e introduza https://mcp.youraiconnector.com/mcp como o URL.
Em Authentication, escolha No sign in. O servidor MCP não tem uma página de início de sessão: escolher uma opção de início de sessão resulta em “Couldn’t register with … sign-in service”.
Em Request headers, adicione um cabeçalho chamado X-API-Key com a sua chave de API como valor.
Clique em Add. As ferramentas Your AI Connector aparecerão no menu de ferramentas de uma nova conversa.

Não vê o campo Request headers? A sua versão do Claude Desktop é antiga: atualize-a ou utilize o ficheiro de configuração. O ficheiro de configuração (claude_desktop_config.json, Settings → Developer → Edit Config) apenas executa programas no seu computador e ignora uma entrada url, pelo que necessita 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 está escrito, sem espaço após os dois pontos (no Windows, um espaço divide o cabeçalho), e coloque a sua chave apenas em env. Depois, feche completamente o Claude Desktop (no Windows, clique com o botão direito no ícone da bandeja → Quit) e abra-o novamente.

ChatGPT

O ChatGPT não consegue ligar-se ao servidor MCP de momento. O seu formulário de conector personalizado apenas oferece OAuth ou Sem autenticação, e o servidor MCP Your AI Connector inicia sessão com a sua chave de API, enviada como um cabeçalho de pedido. Escolher OAuth falha com “could not discover OAuth settings”, e Sem autenticação é recusado porque cada pedido necessita da chave.

Utilize um assistente que lhe permita definir um cabeçalho de pedido: 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 ligação: consulte A documentação de ajuda está integrada para os ficheiros llms.txt públicos.

Cursor e outros clientes MCP

A maioria dos editores compatíveis com MCP utiliza a mesma estrutura .mcp.json apresentada acima (um servidor HTTP com um url e um cabeçalho X-API-Key). Adicione um servidor ai-connector 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 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 pode fazer

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

Agentes de IA: listar, criar, atualizar, pausar/retomar, inspecionar configuração.
Contactos: pesquisar, criar, etiquetar, adicionar a listas, importar.
Base de conhecimento / FAQs: adicionar, editar, importar em massa, aprovar sugestões de 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?”
“Qual é o estado dos canais da Northside Dental e quantos chats foram recebidos esta semana?”

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 funciona da mesma forma. Todas as ações que aceitam uma conta de cliente na API estão disponíveis para um cliente nomeado: configurar agentes de IA, base de conhecimento, funções personalizadas, modelos de WhatsApp, pontos de entrada, ligações de canais, contactos, etiquetas, transmissões, marcações, negócios e tarefas, e envio de mensagens. As exceções são as ações ao nível da agência, que são sempre executadas na sua própria conta de agência: gestão das contas dos clientes (limites, funcionalidades, preços, suspensão), instantâneos, a sua equipa e chaves de API. Adicionar ou remover contactos da lista de um cliente ainda não está disponível para um cliente nomeado; faça-o a partir da chave desse cliente ou na sua conta. O guia da API de agência lista o que é suportado.

As ferramentas de agência encontram-se apenas no endereço padrão, sem marca, https://mcp.youraiconnector.com/mcp. Um endereço MCP de marca branca no seu próprio domínio (mcp.youragency.com) foi criado para os seus clientes e exclui essas ferramentas, por isso, utilize o endereço padrão, sem marca, quando gerir contas de clientes.

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.

Testar o agente de um cliente

Peça ao assistente para experimentar o agente de um cliente (“envia ‘fazem entregas aos domingos?’ ao agente da Padaria do cliente X e mostra-me o que aconteceu”). Este envia uma mensagem de Teste com a sua chave de agência e o sub_account_id do cliente, aguarda e lê a resposta, bem como quaisquer ações que o agente tenha realizado. Não é necessária uma cópia do agente. Se o assistente disser que não tem uma conta de agência, é porque está ligado com a chave de um cliente: volte a ligá-lo com a chave da sua conta de agência. Consulte Experimentar.

Clientes com um limite de ferramentas

Alguns clientes de IA apenas aceitam 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 ligação completa do agente lista mais do que isso, por isso adicione ?tags= ao endereço apenas com os grupos de ferramentas de que necessita.

Para um agente que pretenda listar as contas dos seus clientes, ler os seus contactos, conversas e mensagens, e enviar mensagens:

https://mcp.youraiconnector.com/mcp?tags=SubAccounts,Contacts,Messages

Isso carrega cerca de 80 ferramentas. Nomeie o cliente no seu pedido e o assistente atuará na conta desse cliente, conforme descrito acima.

Separe os grupos com vírgulas; tanto maiúsculas como minúsculas funcionam.
Para adicionar ferramentas individuais, liste os seus nomes exatos com tools=, por exemplo ?tags=Contacts&tools=list_or_get_subaccounts. Obtém todas as ferramentas de qualquer uma das listas.
As ferramentas da documentação de ajuda estão sempre incluídas.
A chave da API continua a ser colocada no cabeçalho X-API-Key (ou Authorization: Bearer YOUR_API_KEY), nunca no endereço.

A documentação de ajuda está integrada

O servidor MCP fornece ao assistente a sua conta e esta documentação. Três ferramentas leem a documentação de ajuda em tempo real, para que o assistente possa consultar o funcionamento de uma funcionalidade ou o que mudou recentemente, em vez de adivinhar:

docs_search: encontra as secções que respondem a uma pergunta e devolve-as com a ligação da página.
docs_read: lê uma página na íntegra ou uma secção da mesma.
docs_list: lista todas as páginas por área.

Não há nada para configurar e as ferramentas de documentação nunca acedem aos dados da sua conta. Pergunte “como funcionam os pontos de entrada?” ou “o que há de novo nas automatizações?” e o assistente pesquisa primeiro na documentação. Como as ferramentas leem o próprio site de ajuda, uma funcionalidade é conhecida pelo seu assistente assim que o respetivo guia é publicado.

Um assistente que não esteja ligado através de MCP ainda pode ler a documentação: aponte-o para https://docs.youraiconnector.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.youraiconnector.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.

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 para ver os passos exatos.

Resolução de Problemas

“Connection refused” ou “not found” — falta o /mcp no final do endereço. 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 um X-API-Key válido.
“Could not discover OAuth settings” (ChatGPT) — o ChatGPT apenas suporta OAuth ou sem autenticação para conectores personalizados, e o servidor MCP utiliza uma chave de API, pelo que o ChatGPT não consegue ligar-se por agora. Consulte ChatGPT.
“Couldn’t register with … sign-in service” ou “add an OAuth Client ID” (Claude Desktop) — o conector personalizado foi adicionado com uma opção de início de sessão. Não existe nenhum ID de cliente OAuth para introduzir: remova o conector e adicione-o novamente com Authentication → No sign in e a sua chave de API como um cabeçalho de pedido X-API-Key, conforme indicado em Claude Desktop.
O Claude Desktop não mostra ferramentas após editar o ficheiro de configuração — o ficheiro de configuração ignora uma entrada "url"; utilize o conector personalizado ou o formulário mcp-remote em Claude Desktop e feche e reabra a aplicação completamente.
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 marca branca podem colocar o endereço MCP no seu próprio domínio (por exemplo, mcp.youragency.com) a partir do cartão Custom domain em Settings → White Labeling — adicione primeiro o CNAME no seu registador, depois introduza o nome de anfitrião no bloco MCP domain (AI assistants) e clique em Verify, o mesmo fluxo que os seus outros subdomínios de marca. O endereço de marca omite as ferramentas da agência; continue a utilizar o endereço padrão, sem marca, para essas. Até que o seu endereço de marca seja verificado, utilize o endereço padrão, sem marca: é seguro partilhá-lo com clientes.

Próximos Passos

Acesso à API — gere ou renove a chave que esta ligação utiliza.
Webhooks — a contraparte baseada em push desta ligação MCP baseada em pull.

Ligar Assistentes de IA (MCP) #

Claude Code #

Claude Desktop #

ChatGPT #

Cursor e outros clientes MCP #

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

O que pode fazer #

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

Testar o agente de um cliente #

Clientes com um limite de ferramentas #

A documentação de ajuda está integrada #

Encontrar ou Gerar a Sua Chave de API #

Resolução de Problemas #

Próximos Passos #