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 e fontes de dados externas. 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 ferramentas que o LLM seleciona.

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

  • List Tools: Busca o manifesto de ferramentas do servidor MCP. Use isto 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 isto após o LLM retornar uma resposta tool_calls.

Este guia aborda a configuração de conexão, recuperação do manifesto de ferramentas e invocação de ferramentas no nível do conector. Para o loop completo de múltiplas rodadas que conecta essas etapas a um LLM, consulte Implementar um loop de chamada de ferramentas de 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 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 no 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 Propósito
Descoberta de Ferramentas List Tools (origem) → Transformação → Atividade de LLM Recuperar o manifesto de ferramentas do servidor MCP e registrá-lo no 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 do projeto, abra a aba Endpoints e conectores do projeto da paleta de componentes de design.

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

  3. Clique em Add New Endpoint para criar uma nova conexão. A tela de configuração de conexão se abre.

  4. Digite um Connection name (Nome da conexão). O nome deve ser único dentro do projeto e não deve conter / ou :.

  5. Em MCP server URL, digite a URL do endpoint completo do servidor MCP, incluindo o protocolo e caminho. Por exemplo, https://api.example.com/mcp.

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

    • No Auth: Nenhuma credencial é necessária.
    • Access Token: Digite um Bearer token emitido pelo servidor MCP ou seu provedor de serviços.
    • Authorization Code Grant: Selecione um aplicativo OAuth configurado em App Registrations e clique em Log in with OAuth. Consulte os pré-requisitos de 3LO para requisitos de configuração. A versão do agente 10.83 / 11.21 ou posterior é necessária.

  7. (Opcional) Clique em Optional settings (Configurações opcionais) para configurar definições adicionais:

    • Protocol Version: Selecione a versão do protocolo MCP. A padrão (2025-06-18) é recomendada, a menos que o servidor MCP exija uma versão específica.
    • Timeout (in milliseconds): Aumente este valor se o servidor MCP for lento para responder. O padrão é 30000 (30 segundos).
    • Custom Request Headers: Adicione todos os headers que o servidor exigir em cada requisição.

  8. Clique em Test para verificar a conexão. Um teste bem-sucedido também faz o download da versão mais recente do conector para o grupo de agentes atribuído ao ambiente atual.

  9. Clique em Save Changes.

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 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.

Part 2: Retrieve the tool manifest

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 da paleta de componentes de design para uma zona de soltura 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 ferramenta MCP para o formato esperado pelo LLM. Consulte Part 3 para obter os detalhes de mapeamento.

Part 3: Map the tool manifest to the LLM format

A resposta de List Tools inclui uma matriz tools. Cada entrada contém os seguintes campos:

MCP field Type Description
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 natural 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 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 LLM (por exemplo, OpenAI ou Amazon Bedrock) que fornece uma atividade Register Tools, coloque essa atividade à direita da transformação como o destino da operação.

Quando a operação é executada, o Jitterbit armazena os esquemas de ferramentas registradas na memória do agente privado. Qualquer operação encadeada para ser executada após esta automaticamente tem acesso a esses esquemas quando chama o LLM. Você não precisa capturar a resposta de Register Tools nem passar as definições de ferramenta explicitamente para a operação Prompt subsequente. Este armazenamento na memória é um recurso de agente privado, e é por isso que 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 ferramenta na memória do agente. As atividades mais novas Register Tools V2 e Register MCP Server Tools do conector OpenAI (usadas com a atividade Prompt V2) também suportam grupos de agentes na nuvem: ative Store chat context across operations na conexão OpenAI para reter as ferramentas registradas e a conversa em 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 de um manifesto de ferramentas incluído em sua solicitação. O Jitterbit fornece os esquemas armazenados da memória do agente automaticamente.

Se 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, consulte 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 e os argumentos da ferramenta e execute-a usando a atividade Invoke Tools.

Extrair a chamada de ferramenta da resposta do LLM

Após a chamada LLM, adicione uma etapa de script para ler a resposta e definir as variáveis da 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âmetros selecionados pelo LLM. Faça parse dela 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 ferramenta paralelas), e qualquer chamada após a primeira é ignorada por este script. Para tratar todas as chamadas, faça um dos seguintes:

  • Desabilite chamadas de ferramenta 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 requer 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 soltar na tela de design.

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

  3. No campo Name, digite 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: Digite [function_name] no campo Tool name. Isso passa a variável contendo o nome da ferramenta selecionada pelo LLM em 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 em 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 depois 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 em 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 ser executada, a resposta do servidor MCP fica 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 mensagens em Implementar um loop de chamada de ferramenta LLM para anexar o resultado à conversa e disparar 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 atribuir a function_resp. O campo content da mensagem tool role na API do LLM requer um valor de string.

Verificar a integração

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

  2. Execute uma chamada LLM de teste com o manifesto de ferramentas registrado. Envie uma mensagem do usuário que corresponda claramente a uma das ferramentas registradas. Confirme nos logs 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 logs 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 do servidor MCP e, em seguida, revise o mapeamento de transformação.

  5. Se o LLM selecionar uma ferramenta que não estiver 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 adequadamente.