# 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](api-access.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 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 →](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 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: ```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. 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). 1. Abra **Customize → Connectors**, clique em **+ Add** e, depois, em **Add custom connector**. 2. Dê-lhe um nome e introduza `https://mcp.youraiconnector.com/mcp` como o URL. 3. 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". 4. Em **Request headers**, adicione um cabeçalho chamado `X-API-Key` com a sua chave de API como valor. 5. 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](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 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-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 ligação: consulte [A documentação de ajuda está integrada](#the-help-docs-are-built-in) 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: ```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 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](../agency/api-for-agencies.md#where-sub_account_id-is-supported) lista o que é suportado. ::: neutral-mcp 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](../chats/playground.md#testing-an-agent-from-the-api-or-an-ai-assistant). ## Clientes com um limite de ferramentas ::: neutral-mcp 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](api-access.md#generating-your-api-key) 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](#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](#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](#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](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.