Ir para o conteúdo

Servidor MCP

O Servidor MCP da BotCity expõe os dados da BotCity Plataforma para assistentes de IA compatíveis com o Model Context Protocol (MCP). Depois de conectado, você consulta a plataforma em linguagem natural, direto do seu assistente, sem abrir o Orquestrador nem escrever chamadas de API.

Pelo Servidor MCP, você pode consultar:

  • Perfil e repositórios: seus dados de usuário, organização e os repositórios aos quais você tem acesso.
  • Automações: listagem, status (por exemplo, rascunho) e distribuição por tecnologia.
  • Logs de execução: schemas disponíveis por repositório e registros gravados em um período.
  • Erros: erros não tratados, detalhes com stacktrace e análises por automação.
  • Alertas: contagens, listagens e quebras por tipo (INFO, WARN, ERROR).
  • Tarefas: execuções por período, status de finalização e tendências.
  • FTE e ROI: horas economizadas, FTE equivalente e retorno sobre investimento das automações.

O servidor usa autenticação OAuth: cada pessoa faz login com a própria conta BotCity e só acessa os dados que já pode ver na plataforma.

Captura de tela do chat do GitHub Copilot respondendo a uma consulta feita pelo Servidor MCP da BotCity. A resposta mostra as ferramentas executadas, uma tabela com o perfil do usuário (nome, e-mail e organização) e outra com os repositórios disponíveis, com as colunas Label, Nome, Descrição e Grupos.

O que você vai precisar

  • Acesso à BotCity Plataforma com permissão para usar os recursos que deseja consultar.
  • Um dos clientes compatíveis: GitHub Copilot (VS Code), Claude Code, Claude Desktop ou Cursor.
  • Os dados de conexão do servidor, listados abaixo.

Dados de conexão

Campo Valor
URL do servidor MCP https://<seu_workspace>.botcity.dev/mcp
Client ID mcp

Nos exemplos de configuração desta página, substitua <URL_DO_SERVIDOR_MCP> e <CLIENT_ID> pelos valores da tabela.

Conectar ao GitHub Copilot

  1. Abra o VS Code com a extensão do GitHub Copilot instalada.
  2. Pressione Ctrl+Shift+P para abrir a Command Palette e digite MCP.

  3. Selecione MCP: Open User Configuration. O VS Code abre o arquivo mcp.json do seu usuário.

    Captura de tela da Command Palette do VS Code filtrada pelo termo MCP, com a opção MCP: Open User Configuration destacada no topo da lista.

  4. Adicione a configuração abaixo ao arquivo:

    {
  "servers": {
    "botcity-mcp": {
      "type": "http",
      "url": "<URL_DO_SERVIDOR_MCP>",
      "oauth": {
        "clientId": "<CLIENT_ID>"
      }
    }
  }
}

  5. Clique em Start, logo acima do nome do servidor no arquivo.

  6. Na mensagem do VS Code pedindo autenticação no servidor, clique em Allow. O navegador abre a tela de login da BotCity.
  7. Faça login com sua conta BotCity e volte ao VS Code.

  8. Confira se o servidor aparece com o status Running.

    Captura de tela do arquivo mcp.json no VS Code, com o servidor botcity-mcp configurado e a indicação Running acima do nome do servidor, junto da quantidade de ferramentas disponíveis.

Em seguida, teste a conexão em uma nova conversa do Copilot.

Sessão expirada no Copilot

Quando o login expira, o Copilot exibe uma mensagem e o VS Code pede uma nova autenticação. Repita os passos 6 e 7.

Conectar ao Claude Code

  1. No terminal, confirme que o Claude Code está instalado:

    claude --version

  2. Registre o servidor:

    claude mcp add --transport http botcity-mcp <URL_DO_SERVIDOR_MCP> --client-id <CLIENT_ID>

    Por padrão, o servidor fica disponível apenas no projeto atual. Para escolher outro escopo, adicione a opção --scope:

    • --scope user: disponível em todos os seus projetos.
    • --scope project: grava a configuração no arquivo .mcp.json na raiz do projeto, para compartilhar com o time pelo repositório.

    Se preferir editar o .mcp.json manualmente, use este formato:

    {
  "mcpServers": {
    "botcity-mcp": {
      "type": "http",
      "url": "<URL_DO_SERVIDOR_MCP>",
      "oauth": {
        "clientId": "<CLIENT_ID>"
      }
    }
  }
}

  3. Verifique se o servidor foi registrado:

    claude mcp list

  4. Se o status for Needs authentication, inicie uma sessão com claude e execute o comando /mcp. Selecione botcity-mcp e escolha Authenticate. O navegador abre a tela de login da BotCity.

    Captura de tela do Claude Code exibindo os detalhes do servidor botcity-mcp após o comando /mcp. O status aparece como needs authentication e a opção Authenticate está selecionada.

  5. Faça login com sua conta BotCity e volte ao terminal.

  6. Confirme que o status mudou para Connected, pelo /mcp ou pelo claude mcp list.

    Captura de tela do Claude Code após o comando /mcp, exibindo a mensagem Authentication successful. Connected to botcity-mcp.

Em seguida, teste a conexão em uma nova sessão do Claude Code.

Renovação do token no Claude Code

O Claude Code tenta renovar o token automaticamente antes que ele expire. Se a sessão expirar mesmo assim, execute /mcp, selecione botcity-mcp e escolha Authenticate para fazer login de novo.

Falha de autenticação sem Dynamic Client Registration

Em algumas versões do Claude Code, a autenticação pode falhar mesmo com o Client ID configurado, quando o provedor de identidade não expõe Dynamic Client Registration (DCR). Se isso acontecer, atualize o Claude Code para a versão mais recente antes de abrir um chamado com o suporte.

Conectar ao Claude Desktop

Em contas Team e Enterprise, o administrador do workspace no Claude cadastra o conector uma única vez para toda a organização. Cada pessoa só precisa localizar o conector e fazer o próprio login.

Vincular um conector já cadastrado

  1. Abra o Claude Desktop e confirme que você está logado com a conta do workspace da sua empresa.

  2. Clique em + no campo de mensagem (ou digite /), passe o mouse sobre Conectores e selecione Gerenciar conectores. Você também chega a essa tela por Configurações > Conectores.

    Captura de tela do Claude Desktop com o menu + aberto no campo de mensagem. O item Conectores está expandido e mostra as opções Navegar conectores e Gerenciar conectores.

  3. Localize o conector da BotCity na lista. Use a busca ou os filtros Todos, Conectado e Não conectado.

  4. Clique em Vincular, ao lado do conector. O navegador abre a tela de login da BotCity.

    Captura de tela da tela Conectores do Claude Desktop, com a busca filtrando o conector da BotCity. A linha do conector mostra o tipo Web Personalizado e o botão Vincular na coluna Status.

  5. Faça login com sua conta BotCity e volte ao Claude Desktop.

  6. Confirme que a coluna Status mostra o ícone de conectado e que a coluna Autorização mostra Individual: o conector é do workspace, mas o login é seu.

    Captura de tela da tela Conectores do Claude Desktop após o login. A linha do conector mostra Individual na coluna Autorização e um ícone de confirmação na coluna Status, e uma notificação no canto inferior direito confirma a conexão. 7. Em uma nova conversa, clique em +, passe o mouse sobre Conectores e ative o conector da BotCity.

Em seguida, teste a conexão nessa conversa.

O conector não aparece na lista?

Se o conector não aparece, ele ainda não foi cadastrado no workspace. Peça ao administrador da conta da sua empresa no Claude para cadastrá-lo, seguindo Cadastrar o conector manualmente. Em contas Team e Enterprise, usuários comuns normalmente só conseguem vincular conectores já cadastrados.

Sessão expirada no Claude Desktop

Quando o token expira, a próxima chamada às ferramentas falha ou o conector volta a exibir Vincular. Repita os passos 4 e 5.

Cadastrar o conector manualmente

Use este fluxo apenas se o conector ainda não existe e você tem permissão para criá-lo: conta individual Pro ou Max, ou administrador de um workspace Team ou Enterprise.

  1. Abra o cadastro de conector personalizado:
    • Conta individual: na tela Conectores, clique em + e escolha Add custom connector.
    • Team ou Enterprise: acesse Settings > Organization Settings > Connectors > Add > Custom > Web.
  2. Em Name, informe um nome para o conector, por exemplo botcity-mcp. Em URL, informe <URL_DO_SERVIDOR_MCP>.
  3. Clique em Advanced settings e informe <CLIENT_ID> em OAuth Client ID. Deixe Client Secret em branco: o client usa um fluxo público (PKCE).
  4. Clique em Add e continue a partir do passo 4 de Vincular um conector já cadastrado.

Limitações do Claude Desktop

  • Cadastro só pela interface: o Claude Desktop não registra servidores MCP remotos com OAuth a partir do arquivo claude_desktop_config.json. Use a tela de Conectores.
  • Conexão feita pela nuvem da Anthropic: a autenticação e as chamadas às ferramentas partem da infraestrutura da Anthropic, não da sua máquina. O servidor MCP precisa estar acessível pela internet pública, ou com os IPs da Anthropic liberados no firewall ou na VPN.
  • Ativação por conversa: o conector precisa ser ativado em cada nova conversa em que você for usá-lo.

Conectar ao Cursor

  1. Abra o Cursor e pressione Ctrl+Shift+P (Windows e Linux) ou Cmd+Shift+P (macOS) para abrir a Command Palette.
  2. Digite MCP e selecione View: Open MCP Settings. Em algumas versões, a opção aparece como Cursor Settings: Tools & MCPs.

  3. Clique em New (ou New MCP Server) e escolha onde salvar a configuração:

    • User: grava em ~/.cursor/mcp.json e vale para todos os projetos.
    • Workspace: grava em .cursor/mcp.json no projeto, para compartilhar com o time pelo repositório.

    Captura de tela da tela de MCPs do Cursor, com o botão New aberto mostrando as opções User e o workspace atual.

  4. Adicione a configuração abaixo ao arquivo mcp.json e salve:

    {
  "mcpServers": {
    "botcity-mcp": {
      "url": "<URL_DO_SERVIDOR_MCP>",
      "auth": {
        "CLIENT_ID": "<CLIENT_ID>"
      }
    }
  }
}

  5. Na lista de MCPs, o servidor botcity-mcp aparece com o status Needs authentication. Clique em Authenticate. O navegador abre a tela de login da BotCity.

    Captura de tela da tela de MCPs do Cursor, com o servidor botcity-mcp na seção Needs Attention e o botão Authenticate à direita.

  6. Faça login com sua conta BotCity e volte ao Cursor.

  7. Confirme que o servidor aparece como conectado (indicador verde). Clique no servidor para ver as ferramentas disponíveis.

    Captura de tela da tela de MCPs do Cursor com o painel Configure botcity-mcp aberto. O painel mostra a origem da configuração em ~/.cursor/mcp.json, o ambiente Local como conectado e a lista de ferramentas do servidor, cada uma com um botão para ativar ou desativar.

Em seguida, teste a conexão em uma nova conversa do Agent.

Sessão expirada no Cursor

Quando o login expira, o Cursor volta a exibir Needs authentication. Clique em Authenticate e faça login de novo.

Testar a conexão

Abra uma nova conversa no cliente que você configurou e envie o prompt abaixo:

Seja um analista de automações RPA da BotCity. Use o servidor MCP configurado para as consultas.
Poderia me mostrar meu perfil de usuário e os repositórios que tenho acesso?

O assistente pede aprovação antes de executar as ferramentas do Servidor MCP. Aprove as chamadas e confira a resposta.

Conexão validada

A conexão está funcionando quando:

  • O cliente lista as ferramentas do Servidor MCP.
  • O assistente executa uma consulta de leitura e retorna seu perfil e seus repositórios.
  • Seu login é feito pela tela da BotCity, sem credenciais gravadas em arquivos de configuração.

Exemplos de prompts

Depois de validar a conexão, use os prompts abaixo como ponto de partida. Substitua os valores entre colchetes por dados da sua organização.

  • Automações: "Liste as automações do repositório [nome do repositório], ordenadas da mais recente para a mais antiga."
  • Automações por tecnologia: "Quantas automações existem por tecnologia (Java, Python, JavaScript, Command) na organização, considerando as criadas nos últimos 90 dias?"
  • Logs de execução: "Quais logs de execução existem para o repositório [nome do repositório]? Quantos registros o log [nome do log] gravou nos últimos 7 dias?"
  • Erros: "Quantos erros não tratados ocorreram na organização no último mês? Liste os detalhes, incluindo o stacktrace."
  • Alertas: "Me dê uma quebra de alertas por automação e por tipo (INFO, WARN, ERROR) nos últimos 90 dias."
  • Tarefas: "Liste as tarefas que falharam no último mês e exporte o resultado como CSV."
  • FTE: "Qual o FTE gerado pelas minhas automações desde abril? Mostre também as 5 automações que mais contribuíram."
  • ROI: "Qual o ROI das automações do repositório [nome do repositório] neste ano?"

Solucionar problemas

Problema O que verificar
Erro 401 ou 403 Se o login foi concluído e se seu usuário tem permissão na plataforma para os recursos consultados. Refaça a autenticação no cliente.
Timeout ou falha de conexão Se a URL do servidor está correta e se sua rede, VPN ou firewall permitem acesso a ela.
Status Needs authentication não muda Se o login na tela da BotCity foi concluído e se o navegador retornou ao cliente. Refaça a autenticação.
As ferramentas não aparecem Se o servidor está conectado no cliente e se o cliente tem suporte a servidores MCP remotos (HTTP). Reinicie o servidor ou o cliente.
Falha de autenticação no Claude Code Se o Claude Code está na versão mais recente. Veja Conectar ao Claude Code.
Conector não aparece no Claude Desktop Se o administrador do workspace já cadastrou o conector. Veja Conectar ao Claude Desktop.

Relacionados