Saltar al contenido

Conectar a un servidor MCP utilizando 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 a las herramientas que el LLM selecciona.

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

  • List Tools: Recupera el manifiesto de herramientas del servidor MCP. Utiliza esto para poblar las herramientas disponibles del LLM antes de cada conversación.
  • Invoke Tools: Ejecuta una herramienta específica en el servidor MCP con los argumentos que el LLM seleccionó. Utiliza esto después de que el LLM devuelve 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 llamadas a herramientas LLM. Para un recorrido completo del agente que ensambla estos componentes en un agente de IA funcional, consulta Cómo construir un agente de IA con MCP.

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

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 List Tools (source) → Transformación → Actividad LLM Recuperar el manifiesto de herramientas del servidor MCP y registrarlo con el LLM.
Invocación de Herramientas Transformación (source) → Invoke Tools (target) Ejecutar la herramienta que el LLM seleccionó y capturar el resultado.

Parte 1: Configurar la conexión del cliente MCP

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

  2. En Puntos finales disponibles, haz clic en Cliente MCP para expandirlo y mostrar los tipos de actividad disponibles.

  3. Haz clic en Agregar nuevo punto final 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 punto final del servidor MCP, incluyendo 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.
    • 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 los requisitos de configuración. Se requiere la versión del agente 10.83 / 11.21 o posterior.

  7. (Opcional) Haz clic en Configuraciones opcionales para configurar ajustes adicionales:

    • Versión del protocolo: Selecciona la versión del protocolo MCP. Se recomienda la predeterminada (2025-06-18) 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 cualquier encabezado que el servidor requiera en cada solicitud.

  8. Haz clic en Probar para verificar la conexión. Una prueba exitosa también descarga la última versión del conector al grupo de agentes asignado al entorno actual.

  9. Haz clic en Guardar cambios.

Nota

Cuando pruebas la conexión, el conector almacena cualquier ID de sesión que el servidor MCP devuelve en los encabezados de respuesta y lo incluye automáticamente en todas las solicitudes subsiguientes. No es necesario 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 actualmente registradas 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 caída 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 mapea las definiciones de herramientas MCP al formato esperado por el LLM. Consulta Parte 3 para los detalles del mapeo.

Parte 3: Mapear el manifiesto de herramientas al formato LLM

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

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

La mayoría de las APIs LLM, incluyendo OpenAI Chat Completions y Azure OpenAI, esperan que las herramientas se pasen 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, mapea name, description e inputSchema a los campos correspondientes en el esquema de solicitud del LLM. Si estás utilizando un conector LLM (por ejemplo, OpenAI o Amazon Bedrock) que proporciona una actividad Register Tools, coloca esa actividad a la derecha de la transformación como el objetivo de la operación.

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

Nota

El requisito del agente privado mencionado anteriormente se aplica a la actividad clásica Registrar Herramientas, que mantiene los esquemas de herramientas en la memoria del agente. Las actividades más nuevas del conector OpenAI Registrar Herramientas V2 y Registrar Herramientas del Servidor MCP (utilizadas con la actividad Prompt V2) también admiten grupos de agentes en la nube: habilite Almacenar contexto de chat a través de operaciones en la conexión de OpenAI para retener las herramientas registradas y la conversación a través de operaciones que comparten el mismo chatId.

Consejo

Solo se necesita una operación Registrar Herramientas por ejecución de flujo de trabajo. La operación Prompt no necesita un manifiesto de herramientas incluido en su solicitud. Jitterbit proporciona automáticamente los esquemas almacenados de la memoria del agente.

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

Parte 4: Invocar una herramienta en el servidor MCP

Cuando el LLM devuelve una respuesta tool_calls, extraiga el nombre de la herramienta y los argumentos, luego ejecute la herramienta utilizando la actividad Invocar Herramientas.

Extraer la llamada a la herramienta de la respuesta del LLM

Después de la llamada al LLM, agrega un paso de script para leer la respuesta y establecer las variables de llamada a la 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 seleccionados por el LLM. Analízalo usando JSONParser para extraer valores individuales antes de pasarlos a la transformación en el siguiente paso.

Manejo de múltiples llamadas a herramientas

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

  • Desactiva las llamadas a herramientas 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 array tool_calls, invocando la herramienta y agregando un mensaje de resultado tool para cada entrada antes de la siguiente llamada al LLM. Usa GetJSONString con un índice que incremente (por ejemplo, tool_calls/1/...) para leer cada llamada, y devuelve un mensaje tool por cada 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 Invocar Herramientas

  1. Arrastra el tipo de actividad Invocar Herramientas desde la paleta de componentes de diseño a una zona de caída en el lienzo de diseño.

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

  3. En el campo Nombre, ingresa un nombre para la actividad (por ejemplo, MCP - Invocar Herramienta).

  4. En Elegir herramienta, selecciona el método para especificar la herramienta:

    • Informar el nombre de la herramienta manualmente: Ingresa [function_name] en el campo Nombre de la herramienta. Esto pasa la variable que contiene el nombre de la herramienta seleccionada por el LLM en tiempo de ejecución, permitiendo que una sola instancia de actividad invoque cualquier herramienta en el servidor MCP.
    • Seleccionar herramienta de la lista: Elige una herramienta específica de la lista en el momento del diseño. Usa este enfoque cuando la operación esté dedicada a una herramienta conocida.

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

  6. Agrega una transformación a la izquierda de la actividad Invocar Herramientas. 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 para la herramienta seleccionada y está disponible en el Paso 2 de la actividad.

Capturar el resultado de la herramienta

Después de que la actividad Invocar Herramientas se ejecute, la respuesta del servidor MCP está disponible a través del esquema de datos de la actividad. Agrega un paso de script o 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 a herramientas LLM para agregar el resultado a la conversación y activar la siguiente llamada LLM.

Nota

Si el resultado de la herramienta es un dato estructurado (por ejemplo, un objeto JSON), sérialo a una cadena antes de asignarlo a function_resp. El campo content del mensaje de rol tool en la API LLM requiere un valor de cadena.

Verificar la integración

  1. Despliega y ejecuta la operación Descubrimiento de Herramientas. En los registros de operación, confirma que la actividad Listar Herramientas devolvió un manifiesto no vacío. Usa WriteToOperationLog para registrar los nombres de las herramientas y verificar que las herramientas esperadas estén listadas.

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

  3. Despliega y ejecuta la operación de Invocación de Herramientas con function_name y function_args configurados para una llamada de herramienta válida. Verifica en los registros que la actividad Invocar Herramientas se completó y que function_resp contiene la salida esperada 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 el mapeo de transformación.

  5. Si el LLM selecciona una herramienta que no está disponible en el servidor MCP (por ejemplo, debido a un desajuste de nombre), 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 adecuadamente.