Ir para o conteúdo

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

Introdução

O Modelo de Contexto de Protocolo (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:

  • Listar Ferramentas: Busca o manifesto da ferramenta do servidor MCP. Use isso para preencher as ferramentas disponíveis do LLM antes de cada conversa.
  • Invocar Ferramentas: Executa uma ferramenta específica no servidor MCP com os argumentos que o LLM selecionou. Use isso após o LLM retornar uma resposta tool_calls.

Este guia cobre a configuração da conexão, a recuperação do manifesto da ferramenta e a invocação da ferramenta no nível do conector. Para o ciclo completo de múltiplas rodadas que conecta esses passos a um LLM, veja Implementar um ciclo de chamada de ferramenta LLM. Para um guia completo de agente que monta esses componentes em um agente de IA funcional, veja Como construir um agente de IA com MCP.

Padrão de design

O ciclo de execução da ferramenta MCP usa duas operações. Uma operação de Descoberta de Ferramenta recupera o manifesto da ferramenta 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 Ferramenta é executada cada vez que o LLM seleciona uma ferramenta e retorna o resultado ao LLM.

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 Propósito
Descoberta de Ferramenta Listar Ferramentas (fonte) → Transformação → Atividade LLM Recuperar o manifesto da ferramenta do servidor MCP e registrá-lo com o LLM.
Invocação de Ferramenta Transformação (fonte) → Invocar Ferramentas (alvo) Executar a ferramenta que o LLM selecionou e capturar o resultado.

Parte 1: Configurar a conexão do cliente MCP

  1. No designer de projetos, abra a aba Endpoints e conectores do projeto do painel de componentes de design.

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

  3. Clique em Adicionar Novo Endpoint para criar uma nova conexão. A tela de configuração da conexão será aberta.

  4. Insira um Nome da conexão. O nome deve ser único dentro do projeto e não pode conter / ou :.

  5. Em URL do servidor MCP, insira a URL completa do endpoint 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 Auth: Nenhuma credencial é necessária.
    • Token de Acesso: Insira um token Bearer emitido pelo servidor MCP ou seu provedor de serviços.
    • Código de Autorização: Selecione um aplicativo OAuth configurado em Registros de Aplicativos e clique em Entrar com OAuth. Consulte os pré-requisitos de 3LO para requisitos de configuração. É necessária a versão do agente 10.83 / 11.21 ou posterior.

  7. (Opcional) Clique em Configurações Opcionais para configurar configurações 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 esse valor se o servidor MCP estiver lento para responder. O padrão é 30000 (30 segundos).
    • Cabeçalhos de Solicitação Personalizados: Adicione quaisquer cabeçalhos que o servidor exija em cada solicitação.

  8. Clique em Testar 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 Salvar Alterações.

Nota

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

Parte 2: Recuperar o manifesto da ferramenta

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 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 do painel de componentes de design para uma zona de drop no canvas 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 do MCP para o formato esperado pelo LLM. Veja Parte 3 para os detalhes do mapeamento.

Parte 3: Mapear o manifesto da ferramenta para o formato 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 nas 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 descrevendo os parâmetros obrigatórios e opcionais da ferramenta.

A maioria das APIs LLM, incluindo OpenAI Chat Completions e Azure OpenAI, espera que as ferramentas sejam 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 LLM (por exemplo, OpenAI ou Amazon Bedrock) que fornece uma atividade Register Tools, coloque essa atividade à direita da transformação como o 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 acesso automático a esses esquemas quando chama o LLM. Você não precisa capturar a resposta de Registrar Ferramentas ou passar as definições de ferramentas explicitamente para a operação Prompt subsequente. Esse armazenamento em memória é uma capacidade do agente privado, razão pela qual um agente privado é necessário para usar a atividade Registrar Ferramentas.

Nota

A exigência do agente privado acima se aplica à atividade clássica Registrar Ferramentas, que mantém os esquemas de ferramentas na memória do agente. As novas atividades Registrar Ferramentas V2 e Registrar Ferramentas do Servidor MCP do conector OpenAI (usadas com a atividade Prompt V2) também suportam grupos de agentes em nuvem: ative Armazenar contexto de chat entre operações na conexão OpenAI para reter as ferramentas registradas e a conversa entre operações que compartilham o mesmo chatId.

Dica

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

Se você estiver chamando o LLM usando o conector HTTP v2, inclua o array de ferramentas serializado no campo tools do corpo da solicitação LLM. Armazene o resultado como uma variável de projeto (por exemplo, mcp_tools_json) para que possa ser reutilizado em cada solicitação LLM sem chamar Listar Ferramentas novamente. Para a construção do corpo da solicitaçã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, e então execute a ferramenta usando a atividade Invocar Ferramentas.

Extraia a chamada da ferramenta da resposta do LLM

Após a chamada do LLM, adicione um passo de script para ler a resposta e definir as variáveis de chamada da 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 dos parâmetros que o LLM selecionou. Analise-a usando JSONParser para extrair valores individuais antes de passá-los para a transformação na próxima etapa.

Tratando múltiplas chamadas de ferramentas

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

  • Desative chamadas de ferramentas paralelas na solicitação do 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 solicitaçã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 do LLM. Use GetJSONString com um índice crescente (por exemplo, tool_calls/1/...) para ler cada chamada e retornar uma mensagem tool por tool_call_id. A API do LLM requer um resultado tool correspondente para cada tool_call_id na mensagem do assistente.

Configure a atividade Invocar Ferramentas

  1. Arraste o tipo de atividade Invocar Ferramentas do painel de componentes de design para uma zona de queda no canvas de design.

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

  3. No campo Nome, insira um nome para a atividade (por exemplo, MCP - Invocar Ferramenta).

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

    • Informar o nome da ferramenta manualmente: Insira [function_name] no campo Nome da ferramenta. Isso passa a variável que contém o nome da ferramenta selecionada pelo LLM em tempo de execução, permitindo que uma única instância da atividade invoque qualquer ferramenta no servidor MCP.
    • Selecionar ferramenta da lista: Escolha uma ferramenta específica da lista no momento do design. Use essa abordagem quando a operação for dedicada a uma ferramenta conhecida.

  5. Clique em Próximo para revisar o esquema de dados da ferramenta selecionada e, em seguida, clique em Concluído.

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

Capture o resultado da ferramenta

Após a execução da atividade Invocar Ferramentas, a resposta do servidor MCP está disponível através do esquema de dados da atividade. Adicione um passo de script ou transformação após a atividade para atribuir o resultado da ferramenta a function_resp. Passe function_resp para o passo de construção da mensagem em Implementar um loop de chamada de ferramenta LLM para anexar o resultado à conversa e acionar 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 de papel tool na API LLM requer um valor de string.

Verifique a integração

  1. Implante e execute a operação Descoberta de Ferramentas. Nos logs da operação, confirme que a atividade Listar Ferramentas 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 uma chamada de teste LLM com o manifesto da ferramenta registrado. Envie uma mensagem do usuário que corresponda claramente a uma das ferramentas registradas. Confirme nos logs que a resposta 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 de Invocação de Ferramentas com function_name e function_args definidos para uma chamada de ferramenta válida. Verifique nos logs que a atividade Invocar Ferramentas 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 esquema, clique em Refresh na Etapa 2 da atividade para regenerar o esquema a partir do servidor MCP, em seguida, revise 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 retorna um erro. Ative Continue on error na configuração da atividade para registrar o erro sem interromper a operação, em seguida, retorne uma mensagem de erro descritiva ao LLM como resultado da ferramenta para que o modelo possa responder adequadamente.