Saltar al contenido

Conectarse a un servidor MCP usando el conector MCP Client en Jitterbit Studio

Introducción

El Protocolo de Contexto de Modelo (MCP) es un estándar abierto para conectar LLMs a herramientas externas y fuentes de datos. Un servidor MCP expone una colección de herramientas nombradas, cada una con un esquema de entrada definido. Un cliente MCP descubre esas herramientas, pasa sus esquemas a un LLM como funciones disponibles y ejecuta las llamadas de herramienta que el LLM selecciona.

El conector MCP Client proporciona dos actividades que cubren el ciclo de llamada de herramientas:

  • Listar herramientas: Obtiene el manifiesto de herramientas del servidor MCP. Úsalo para completar las herramientas disponibles del LLM antes de cada conversación.
  • Invocar herramientas: Ejecuta una herramienta específica en el servidor MCP con los argumentos que el LLM seleccionó. Úsalo después de que el LLM devuelva una respuesta tool_calls.

Esta guía cubre la configuración de la conexión, la recuperación del manifiesto de herramientas y la invocación de herramientas a nivel de conector. Para el ciclo completo de múltiples rondas que conecta estos pasos a un LLM, consulta Implementar un ciclo de llamada de herramientas LLM. Para un recorrido completo del agente que ensambla estos componentes en un agente de IA funcional, consulta Cómo crear un agente de IA con MCP. Si el servidor MCP al que te conectas fue creado en Jitterbit MCP, consulta Conectarse a un servidor Jitterbit MCP usando el conector MCP Client para encontrar la URL del servidor y el token de autenticación.

Patrón de diseño

El ciclo de ejecución de herramientas MCP utiliza dos operaciones. Una operación de Descubrimiento de herramientas recupera el manifiesto de herramientas una sola vez (o al inicio de cada sesión) y registra las herramientas disponibles con el LLM. Una operación de Invocación de herramientas se ejecuta cada vez que el LLM selecciona una herramienta y devuelve el resultado al 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"]
Operación Pasos Propósito
Descubrimiento de herramientas Listar herramientas (origen) → Transformación → actividad LLM Recupera el manifiesto de herramientas del servidor MCP y lo registra con el LLM.
Invocación de herramientas Transformación (origen) → Invocar herramientas (destino) Ejecuta la herramienta que el LLM seleccionó y captura el resultado.

Parte 1: Configurar la conexión MCP Client

  1. En el diseñador de proyectos, abre la pestaña Extremos del proyecto y conectores de la paleta del componente de diseño.

  2. En Extremos disponibles, haz clic en MCP Client para expandirlo y mostrar los tipos de actividad disponibles.

  3. Haz clic en Agregar nuevo extremo para crear una nueva conexión. Se abre la pantalla de configuración de la conexión.

  4. Ingresa un Nombre de conexión. El nombre debe ser único dentro del proyecto y no debe contener / o :.

  5. En URL del servidor MCP, ingresa la URL completa del extremo del servidor MCP, incluidos el protocolo y la ruta. Por ejemplo, https://api.example.com/mcp.

  6. En Mecanismo de autenticación, selecciona la opción que coincida con el servidor MCP:

    • Sin autenticación: No se requieren credenciales.
    • Token de acceso: Ingresa un token Bearer emitido por el servidor MCP o su proveedor de servicios.
    • Concesión de código de autorización: Selecciona una aplicación OAuth configurada en Registros de aplicaciones y haz clic en Iniciar sesión con OAuth. Consulta los requisitos previos de 3LO para conocer los requisitos de configuración. Se requiere la versión 10.83 / 11.21 del agente o posterior.

  7. (Opcional) Haz clic en Configuración opcional para configurar opciones adicionales:

    • Versión del protocolo: Selecciona la versión del protocolo MCP. La opción predeterminada (2025-06-18) es recomendada a menos que el servidor MCP requiera una versión específica.
    • Tiempo de espera (en milisegundos): Aumenta este valor si el servidor MCP es lento para responder. El valor predeterminado es 30000 (30 segundos).
    • Encabezados de solicitud personalizados: Agrega los encabezados que el servidor requiere en cada solicitud.

  8. Haz clic en Test para verificar la conexión. Una prueba exitosa también descarga la versión más reciente del conector al grupo de agentes asignado al ambiente actual.

  9. Haz clic en Save Changes.

Nota

Cuando pruebas la conexión, el conector almacena cualquier ID de sesión que el servidor MCP devuelva en los encabezados de respuesta e lo incluye en todas las solicitudes posteriores automáticamente. No necesitas agregar el ID de sesión como un encabezado de solicitud personalizado.

Parte 2: Recuperar el manifiesto de herramientas

La actividad List Tools recupera todas las herramientas registradas actualmente en el servidor MCP. Cada entrada de herramienta incluye su nombre, descripción y esquema de entrada. Ejecuta esta operación antes de la primera llamada LLM en un flujo de trabajo, o al inicio de cada sesión si el conjunto de herramientas del servidor cambia dinámicamente.

  1. Arrastra el tipo de actividad List Tools desde la paleta de componentes de diseño a una zona de destino en el lienzo de diseño. Se crea una nueva operación.

  2. Haz doble clic en la actividad para abrir su configuración.

  3. En el campo Name, ingresa un nombre para la actividad (por ejemplo, MCP - List Tools).

  4. Haz clic en Next para proceder al paso 2, donde se muestra el esquema de respuesta devuelto por el servidor MCP. Haz clic en Refresh si el esquema no aparece.

  5. Haz clic en Finished.

  6. Agrega una transformación a la derecha de la actividad List Tools en la misma operación. La transformación asigna las definiciones de herramientas MCP al formato esperado por el LLM. Consulta Parte 3 para obtener detalles de asignación.

Parte 3: Asignar el manifiesto de herramientas al formato del LLM

La respuesta de List Tools incluye un arreglo tools. Cada entrada contiene los siguientes campos:

MCP field Type Description
name String El identificador único de la herramienta, utilizado en respuestas de tool_calls y como entrada para la actividad Invoke Tools.
description String Una descripción en lenguaje natural que el LLM utiliza para decidir cuándo llamar la herramienta.
inputSchema Object Un objeto JSON Schema que describe los parámetros requeridos y opcionales de la herramienta.

La mayoría de las API de LLM, incluidas OpenAI Chat Completions y Azure OpenAI, esperan herramientas pasadas como esquemas de función:

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

En la transformación después de List Tools, asigna name, description e inputSchema a los campos correspondientes en el esquema de solicitud del LLM. Si utilizas un conector LLM (por ejemplo, OpenAI, Amazon Bedrock, u Ollama) que proporciona una actividad Register Tools, coloca esa actividad a la derecha de la transformación como destino de la operación.

Cuando se ejecuta la operación, Jitterbit almacena los esquemas de herramientas registrados en memoria en el agente privado. Cualquier operación encadenada para ejecutarse después de esta automáticamente tiene acceso a esos esquemas cuando llama al LLM. No necesitas capturar la respuesta de Register Tools ni pasar las definiciones de herramientas explícitamente a la operación Prompt posterior. Este almacenamiento en memoria es una capacidad del agente privado, por eso se requiere un agente privado para utilizar la actividad Register Tools.

Nota

El requisito de agente privado anterior se aplica a la actividad clásica Register Tools, que mantiene esquemas de herramientas en memoria del agente. Las actividades más recientes Register Tools V2 y Register MCP Server Tools del conector OpenAI (utilizadas con la actividad Prompt V2) también soportan grupos de agentes en la nube: habilita Store chat context across operations en la conexión OpenAI para retener las herramientas registradas y la conversación entre operaciones que comparten el mismo chatId.

Consejo

Solo se necesita una operación Register Tools por ejecución de flujo de trabajo. La operación Prompt no necesita que un manifiesto de herramientas se incluya en su solicitud. Jitterbit suministra los esquemas almacenados desde la memoria del agente automáticamente.

Si estás llamando al LLM usando el conector HTTP v2, incluye el arreglo de herramientas serializado en el campo tools del cuerpo de la solicitud del LLM. Guarda el resultado como una variable de proyecto (por ejemplo, mcp_tools_json) para que pueda reutilizarse en cada solicitud del LLM sin llamar a List Tools nuevamente. Para la construcción del cuerpo de la solicitud del LLM y la configuración de la llamada HTTP v2, consulta Llamar a una API REST usando el conector HTTP v2.

Parte 4: Invocar una herramienta en el servidor MCP

Cuando el LLM devuelve una respuesta de tool_calls, extrae el nombre de la herramienta y los argumentos, luego ejecuta la herramienta usando la actividad Invoke Tools.

Extraer la llamada de herramienta de la respuesta del LLM

Después de la llamada del LLM, añade un paso de script para leer la respuesta y establecer las variables de llamada de herramienta:

$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 debe coincidir exactamente con el valor name devuelto por List Tools y definido en el servidor MCP. function_args es una cadena JSON que contiene los valores de parámetro que seleccionó el LLM. Analízala usando JSONParser para extraer valores individuales antes de pasarlos a la transformación en el siguiente paso.

Manejo de múltiples llamadas de herramienta

El script anterior lee tool_calls/0, la primera llamada de herramienta en la respuesta. Un LLM puede devolver varias llamadas de herramienta en una sola respuesta (llamadas de herramienta paralelas), y cualquier llamada después de la primera se ignora por este script. Para manejar cada llamada, haz una de las siguientes opciones:

  • Desactiva las llamadas de herramienta paralelas en la solicitud del LLM para que el modelo devuelva como máximo una llamada por respuesta. Para las APIs de OpenAI y Azure OpenAI Chat Completions, establece parallel_tool_calls en false en el cuerpo de la solicitud.
  • Itera sobre el arreglo tool_calls, invocando la herramienta y añadiendo un mensaje de resultado tool para cada entrada antes de la siguiente llamada del LLM. Usa GetJSONString con un índice incremental (por ejemplo, tool_calls/1/...) para leer cada llamada, y devuelve un mensaje tool por tool_call_id. La API del LLM requiere un resultado tool coincidente para cada tool_call_id en el mensaje del asistente.

Configurar la actividad Invoke Tools

  1. Arrastra el tipo de actividad Invoke Tools desde la paleta de componentes de diseño a una zona de colocación en el lienzo de diseño.

  2. Haz doble clic en la actividad para abrir su configuración.

  3. En el campo Name, ingresa un nombre para la actividad (por ejemplo, MCP - Invoke Tool).

  4. Bajo Choose tool, selecciona el método para especificar la herramienta:

    • Inform tool name manually: Ingresa [function_name] en el campo Tool name. Esto pasa la variable que contiene el nombre de herramienta seleccionado por el LLM en tiempo de ejecución, permitiendo que una sola instancia de actividad invoque cualquier herramienta en el servidor MCP.
    • Select tool from list: Elige una herramienta específica de la lista en tiempo de diseño. Usa este enfoque cuando la operación está dedicada a una herramienta conocida.

  5. Haz clic en Next para revisar el esquema de datos de la herramienta seleccionada, luego haz clic en Finished.

  6. Añade una transformación a la izquierda de la actividad Invoke Tools. La transformación mapea los valores de argumento extraídos de function_args a los campos de entrada definidos en el inputSchema de la herramienta. El esquema es específico de la herramienta seleccionada y está disponible en el Paso 2 de la actividad.

Capturar el resultado de la herramienta

Después de que se ejecute la actividad Invoke Tools, la respuesta del servidor MCP está disponible a través del esquema de datos de la actividad. Añade un paso de script o una transformación después de la actividad para asignar el resultado de la herramienta a function_resp. Pasa function_resp al paso de construcción de mensajes en Implementar un bucle de llamada de herramienta del LLM para añadir el resultado a la conversación e activar la siguiente llamada del LLM.

Nota

Si el resultado de la herramienta es datos estructurados (por ejemplo, un objeto JSON), serialízalo a una cadena antes de asignarlo a function_resp. El campo content del mensaje con rol tool en la API del LLM requiere un valor de cadena.

Verificar la integración

  1. Implementa y ejecuta la operación Tool Discovery. En los registros de operación, confirma que la actividad List Tools devolvió un manifiesto no vacío. Usa WriteToOperationLog para registrar los nombres de las herramientas y verifica que las herramientas esperadas estén listadas.

  2. Ejecuta una llamada LLM de prueba con el manifiesto de herramientas registrado. Envía un mensaje de usuario que corresponda claramente con una de las herramientas registradas. Confirma en los registros que la respuesta del LLM contiene una entrada tool_calls y que function_name coincide con un nombre de herramienta del manifiesto.

  3. Implementa y ejecuta la operación Tool Invocation con function_name y function_args establecidos en una llamada de herramienta válida. Verifica en los registros que la actividad Invoke Tools se completó y que function_resp contiene el resultado esperado del servidor MCP.

  4. Si la actividad Invoke Tools falla con un error de esquema, haz clic en Refresh en el Paso 2 de la actividad para regenerar el esquema desde el servidor MCP, luego revisa la asignación de transformación.

  5. Si el LLM selecciona una herramienta que no está disponible en el servidor MCP (por ejemplo, debido a una falta de coincidencia de nombres), la actividad Invoke Tools devuelve un error. Habilita Continue on error en la configuración de la actividad para registrar el error sin detener la operación, luego devuelve un mensaje de error descriptivo al LLM como resultado de la herramienta para que el modelo pueda responder apropiadamente.