Ir para o conteúdo

Conectar a um servidor MCP usando o conector MCP Client no Jitterbit Studio

Introdução

O Model Context Protocol (MCP) é um padrão aberto para conectar LLMs a ferramentas externas e fontes de dados. Um servidor MCP expõe uma coleção de ferramentas nomeadas, cada uma com um esquema de entrada definido. Um cliente MCP descobre essas ferramentas, passa seus esquemas para um LLM como funções disponíveis e executa as chamadas de ferramenta que o LLM seleciona.

O conector MCP Client fornece duas atividades que cobrem o ciclo de chamada de ferramentas:

  • List Tools: Obtém o manifesto de ferramentas do servidor MCP. Use isso para preencher as ferramentas disponíveis do LLM antes de cada conversa.
  • Invoke Tools: Executa uma ferramenta específica no servidor MCP com os argumentos que o LLM selecionou. Use isso depois que o LLM retorna uma resposta tool_calls.

Este guia cobre a configuração de conexão, a recuperação do manifesto de ferramentas e a invocação de ferramentas no nível do conector. Para o loop completo de várias rodadas que conecta essas etapas a um LLM, consulte Implementar um loop de chamada de ferramentas LLM. Para um passo a passo completo de agente que monta esses componentes em um agente de IA funcional, consulte Como criar um agente de IA com MCP. Se o servidor MCP ao qual você está se conectando foi criado em Jitterbit MCP, consulte Conectar a um servidor Jitterbit MCP usando o conector MCP Client para encontrar a URL do servidor e o token de autenticação.

Padrão de design

O ciclo de execução de ferramentas MCP usa duas operações. Uma operação de Descoberta de Ferramentas recupera o manifesto de ferramentas uma vez (ou no início de cada sessão) e registra as ferramentas disponíveis com o LLM. Uma operação de Invocação de Ferramentas é executada cada vez que o LLM seleciona uma ferramenta e retorna o resultado ao LLM.

%%{init: {"themeVariables": {"lineColor": "#6b7280", "edgeLabelBackground": "#f5f5f5"}}}%% flowchart LR A["MCP Client
List Tools"] --> B["Transformation
Map to LLM
tool schemas"] B --> C["LLM call
(tools registered)"] C --> D{"tool_calls
in response?"} D -->|Yes| E["Script
Extract tool name
and arguments"] E --> F["Transformation
Map arguments
to tool input"] F --> G["MCP Client
Invoke Tools"] G --> H["Script
Append result
to messages"] H --> C D -->|No| I["Final LLM
response"]
Operação Etapas Objetivo
Descoberta de Ferramentas List Tools (origem) → Transformação → atividade LLM Recuperar o manifesto de ferramentas do servidor MCP e registrá-lo com o LLM.
Invocação de Ferramentas Transformação (origem) → Invoke Tools (destino) Executar a ferramenta que o LLM selecionou e capturar o resultado.

Parte 1: Configurar a conexão MCP Client

  1. No designer de projeto, abra a aba Pontos de extremidade e conectores do projeto da paleta de componentes de design.

  2. Em Pontos de extremidade disponíveis, clique em MCP Client para expandi-lo e mostrar os tipos de atividade disponíveis.

  3. Clique em Adicionar novo ponto de extremidade para criar uma nova conexão. A tela de configuração de conexão é aberta.

  4. Digite um Nome da conexão. O nome deve ser exclusivo no projeto e não deve conter / ou :.

  5. Em URL do servidor MCP, digite a URL completa do ponto de extremidade do servidor MCP, incluindo o protocolo e o caminho. Por exemplo, https://api.example.com/mcp.

  6. Em Mecanismo de autenticação, selecione a opção que corresponde ao servidor MCP:

    • Sem autenticação: Nenhuma credencial é necessária.
    • Token de acesso: Digite um token Bearer emitido pelo servidor MCP ou seu provedor de serviço.
    • Concessão de código de autorização: Selecione um aplicativo OAuth configurado em Registros de aplicativos e clique em Fazer login com OAuth. Consulte os pré-requisitos de 3LO para saber os requisitos de configuração. A versão do agente 10.83 / 11.21 ou posterior é necessária.
  7. (Opcional) Clique em Configurações opcionais para configurar ajustes adicionais:

    • Versão do protocolo: Selecione a versão do protocolo MCP. A versão padrão (2025-06-18) é recomendada, a menos que o servidor MCP exija uma versão específica.
    • Tempo limite (em milissegundos): Aumente este valor se o servidor MCP for lento para responder. O padrão é 30000 (30 segundos).
    • Cabeçalhos de solicitação personalizados: Adicione todos os cabeçalhos que o servidor exige em cada solicitação.
  8. Clique em Test para verificar a conexão. Um teste bem-sucedido também baixa a versão mais recente do conector para o grupo de agentes atribuído ao ambiente atual.

  9. Clique em Save Changes.

Nota

Ao testar a conexão, o conector armazena qualquer ID de sessão que o servidor MCP retorna nos cabeçalhos de resposta e o inclui em todas as solicitações subsequentes automaticamente. Você não precisa adicionar o ID de sessão como um cabeçalho de solicitação personalizado.

Parte 2: Recuperar o manifesto de ferramentas

A atividade List Tools recupera todas as ferramentas atualmente registradas no servidor MCP. Cada entrada de ferramenta inclui seu nome, descrição e esquema de entrada. Execute esta operação antes da primeira chamada de LLM em um fluxo de trabalho, ou no início de cada sessão se o conjunto de ferramentas do servidor mudar dinamicamente.

  1. Arraste o tipo de atividade List Tools da paleta de componentes de design para uma zona de destino na tela de design. Uma nova operação é criada.

  2. Clique duas vezes na atividade para abrir sua configuração.

  3. No campo Name, insira um nome para a atividade (por exemplo, MCP - List Tools).

  4. Clique em Next para prosseguir para a Etapa 2, onde o esquema de resposta retornado pelo servidor MCP é exibido. Clique em Refresh se o esquema não aparecer.

  5. Clique em Finished.

  6. Adicione uma transformação à direita da atividade List Tools na mesma operação. A transformação mapeia as definições de ferramentas MCP para o formato esperado pelo LLM. Consulte a Parte 3 para obter detalhes de mapeamento.

Parte 3: Mapear o manifesto de ferramentas para o formato do LLM

A resposta List Tools inclui um array tools. Cada entrada contém os seguintes campos:

Campo MCP Tipo Descrição
name String O identificador único da ferramenta, usado em respostas tool_calls e como entrada para a atividade Invoke Tools.
description String Uma descrição em linguagem simples que o LLM usa para decidir quando chamar a ferramenta.
inputSchema Object Um objeto JSON Schema que descreve os parâmetros obrigatórios e opcionais da ferramenta.

A maioria das APIs de LLM, incluindo OpenAI Chat Completions e Azure OpenAI, espera ferramentas passadas como esquemas de função:

{
  "type": "function",
  "function": {
    "name": "<tool name>",
    "description": "<tool description>",
    "parameters": { "<inputSchema contents>" }
  }
}

Na transformação após List Tools, mapeie name, description e inputSchema para os campos correspondentes no esquema de solicitação do LLM. Se você estiver usando um conector de LLM (por exemplo, OpenAI, Amazon Bedrock ou Ollama) que fornece uma atividade Register Tools, coloque essa atividade à direita da transformação como alvo da operação.

Quando a operação é executada, o Jitterbit armazena os esquemas de ferramentas registrados na memória do agente privado. Qualquer operação encadeada para ser executada após esta tem automaticamente acesso a esses esquemas ao chamar o LLM. Você não precisa capturar a resposta Register Tools nem passar as definições de ferramentas explicitamente para a operação Prompt subsequente. Esse armazenamento na memória é uma capacidade do agente privado, razão pela qual um agente privado é necessário para usar a atividade Register Tools.

Nota

O requisito de agente privado acima se aplica à atividade clássica Register Tools, que mantém esquemas de ferramentas na memória do agente. As atividades mais recentes Register Tools V2 e Register MCP Server Tools do conector OpenAI (usadas com a atividade Prompt V2) também oferecem suporte a grupos de agentes em nuvem: ative Store chat context across operations na conexão OpenAI para manter as ferramentas registradas e a conversa entre operações que compartilham o mesmo chatId.

Dica

Apenas uma operação Register Tools é necessária por execução de fluxo de trabalho. A operação Prompt não precisa incluir um manifesto de ferramentas em sua solicitação. O Jitterbit fornece os esquemas armazenados da memória do agente automaticamente.

Se você está chamando o LLM usando o conector HTTP v2, inclua o array de ferramentas serializado no campo tools do corpo da requisição LLM. Armazene o resultado como uma variável de projeto (por exemplo, mcp_tools_json) para que possa ser reutilizado em cada requisição LLM sem chamar List Tools novamente. Para construção do corpo da requisição LLM e configuração da chamada HTTP v2, veja Chamar uma API REST usando o conector HTTP v2.

Parte 4: Invocar uma ferramenta no servidor MCP

Quando o LLM retorna uma resposta tool_calls, extraia o nome da ferramenta e os argumentos, depois execute a ferramenta usando a atividade Invoke Tools.

Extrair a chamada de ferramenta da resposta do LLM

Após a chamada do LLM, adicione uma etapa de script para ler a resposta e definir as variáveis de chamada de ferramenta:

$tool_call_id  = TrimChars(GetJSONString($jitterbit.response,
                     "/choices/0/message/tool_calls/0/id"), "\"");
$function_name = TrimChars(GetJSONString($jitterbit.response,
                     "/choices/0/message/tool_calls/0/function/name"), "\"");
$function_args = GetJSONString($jitterbit.response,
                     "/choices/0/message/tool_calls/0/function/arguments");

function_name deve corresponder exatamente ao valor name retornado por List Tools e definido no servidor MCP. function_args é uma string JSON contendo os valores de parâmetro que o LLM selecionou. Analise-a usando JSONParser para extrair valores individuais antes de passá-los para a transformação na próxima etapa.

Tratamento de múltiplas chamadas de ferramenta

O script acima lê tool_calls/0, a primeira chamada de ferramenta na resposta. Um LLM pode retornar várias chamadas de ferramenta em uma única resposta (chamadas de ferramentas paralelas), e quaisquer chamadas após a primeira são ignoradas por este script. Para processar todas as chamadas, faça um dos seguintes:

  • Desative chamadas de ferramentas paralelas na requisição LLM para que o modelo retorne no máximo uma chamada por resposta. Para as APIs OpenAI e Azure OpenAI Chat Completions, defina parallel_tool_calls como false no corpo da requisição.
  • Itere sobre o array tool_calls, invocando a ferramenta e anexando uma mensagem de resultado tool para cada entrada antes da próxima chamada LLM. Use GetJSONString com um índice incrementado (por exemplo, tool_calls/1/...) para ler cada chamada e retornar uma mensagem tool por tool_call_id. A API do LLM exige um resultado tool correspondente para cada tool_call_id na mensagem do assistente.

Configurar a atividade Invoke Tools

  1. Arraste o tipo de atividade Invoke Tools da paleta de componentes de design para uma zona de soltura na tela de design.

  2. Clique duas vezes na atividade para abrir sua configuração.

  3. No campo Name, insira um nome para a atividade (por exemplo, MCP - Invoke Tool).

  4. Em Choose tool, selecione o método para especificar a ferramenta:

    • Inform tool name manually: Insira [function_name] no campo Tool name. Isso passa a variável contendo o nome da ferramenta selecionada pelo LLM no tempo de execução, permitindo que uma única instância de atividade invoque qualquer ferramenta no servidor MCP.
    • Select tool from list: Escolha uma ferramenta específica da lista no tempo de design. Use essa abordagem quando a operação é dedicada a uma ferramenta conhecida.
  5. Clique em Next para revisar o esquema de dados da ferramenta selecionada e clique em Finished.

  6. Adicione uma transformação à esquerda da atividade Invoke Tools. A transformação mapeia os valores de argumentos extraídos de function_args para os campos de entrada definidos no inputSchema da ferramenta. O esquema é específico da ferramenta selecionada e está disponível na Etapa 2 da atividade.

Capturar o resultado da ferramenta

Após a atividade Invoke Tools executar, a resposta do servidor MCP está disponível através do esquema de dados da atividade. Adicione uma etapa de script ou transformação após a atividade para atribuir o resultado da ferramenta a function_resp. Passe function_resp para a etapa de construção de mensagem em Implementar um loop de chamada de ferramenta do LLM para anexar o resultado à conversa e desencadear a próxima chamada LLM.

Nota

Se o resultado da ferramenta for dados estruturados (por exemplo, um objeto JSON), serialize-o para uma string antes de atribuí-lo a function_resp. O campo content da mensagem da função tool na API do LLM requer um valor de string.

Verificar a integração

  1. Implante e execute a operação Tool Discovery. Nos registros de operação, confirme que a atividade List Tools retornou um manifesto não vazio. Use WriteToOperationLog para registrar os nomes das ferramentas e verificar se as ferramentas esperadas estão listadas.

  2. Execute um teste de chamada LLM com o manifesto de ferramentas registrado. Envie uma mensagem do usuário que corresponda claramente a uma das ferramentas registradas. Confirme nos registros que a resposta do LLM contém uma entrada tool_calls e que function_name corresponde a um nome de ferramenta do manifesto.

  3. Implante e execute a operação Tool Invocation com function_name e function_args definidos para uma chamada de ferramenta válida. Verifique nos registros que a atividade Invoke Tools foi concluída e que function_resp contém a saída esperada do servidor MCP.

  4. Se a atividade Invoke Tools falhar com um erro de schema, clique em Refresh na Etapa 2 da atividade para regenerar o schema a partir do servidor MCP e, em seguida, analise o mapeamento de transformação.

  5. Se o LLM selecionar uma ferramenta que não está disponível no servidor MCP (por exemplo, devido a uma incompatibilidade de nome), a atividade Invoke Tools retornará um erro. Ative Continue on error na configuração da atividade para registrar o erro sem interromper a operação e, em seguida, retorne uma mensagem de erro descritiva ao LLM como resultado da ferramenta para que o modelo possa responder apropriadamente.