Saltar al contenido

Conectar 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 y fuentes de datos externas. 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 herramientas que el LLM selecciona.

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

  • Listar herramientas: Obtiene el manifiesto de herramientas del servidor MCP. Úsalo para rellenar 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 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 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 estás conectando fue creado en Jitterbit MCP, consulta Conectar a un servidor MCP de Jitterbit 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 Puntos finales y conectores de proyecto de la paleta de componentes de diseño.

  2. En Puntos finales disponibles, haz clic en MCP Client 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 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 del punto final completo 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 los requisitos de configuración. Se requiere la versión del agente 10.83 / 11.21 o posterior.

  7. (Opcional) Haz clic en Configuración opcional para establecer parámetros adicionales:

    • Versión del protocolo: Selecciona la versión del protocolo MCP. La versión predeterminada (2025-06-18) se recomienda 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 al responder. El predeterminado es 30000 (30 segundos).
    • Encabezados de solicitud personalizados: Agrega cualquier encabezado que el servidor requiera 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 entorno 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 devuelve en los encabezados de respuesta e lo incluye automáticamente en todas las solicitudes posteriores. No es necesario agregar el ID de sesión como encabezado de solicitud personalizado.

Part 2: Retrieve the tool manifest

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 colocación 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 continuar 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 Part 3 para obtener los detalles de la asignación.

Part 3: Map the tool manifest to the LLM format

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 a la actividad Invoke Tools.
description String Una descripción en lenguaje natural que el LLM utiliza para decidir cuándo llamar a la herramienta.
inputSchema Object Un objeto de esquema JSON que describe los parámetros requeridos y opcionales de la herramienta.

La mayoría de las API de LLM, incluyendo OpenAI Chat Completions y Azure OpenAI, esperan herramientas pasadas como esquemas de funciones:

{
  "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 o Amazon Bedrock) que proporciona una actividad Register Tools, coloca esa actividad a la derecha de la transformación como destino de la operación.

Cuando la operación se ejecuta, Jitterbit almacena los esquemas de herramientas registradas 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 es necesario capturar la respuesta de Register Tools ni pasar explícitamente las definiciones de herramientas a la operación Prompt posterior. Este almacenamiento en memoria es una capacidad del agente privado, por lo que se requiere un agente privado para utilizar la actividad Register Tools.

Nota

El requisito del agente privado anterior se aplica a la actividad clásica Register Tools, que mantiene esquemas de herramientas en la memoria del agente. Las actividades más recientes del conector OpenAI Register Tools V2 y Register MCP Server Tools (utilizadas con la actividad Prompt V2) también son compatibles con grupos de agentes en la nube: habilita Store chat context across operations en la conexión de 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 un manifiesto de herramientas incluido en su solicitud. Jitterbit suministra automáticamente los esquemas almacenados desde la memoria del agente.

Si está llamando al LLM usando el conector HTTP v2, incluya el arreglo de herramientas serializado en el campo tools del cuerpo de la solicitud del LLM. Guarde el resultado como una variable de proyecto (por ejemplo, mcp_tools_json) para que se pueda reutilizar 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, consulte 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 tool_calls, extraiga el nombre de la herramienta y los argumentos, luego ejecute la herramienta usando la actividad Invoke Tools.

Extraer la llamada de herramienta de la respuesta del LLM

Después de la llamada del LLM, agregue 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ámetros que seleccionó el LLM. Analícela 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 mediante este script. Para manejar cada llamada, realice una de las siguientes acciones:

  • Deshabilite 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 Chat Completions de OpenAI y Azure OpenAI, establezca parallel_tool_calls en false en el cuerpo de la solicitud.
  • Itere sobre el arreglo tool_calls, invoque la herramienta y agregue un mensaje de resultado tool para cada entrada antes de la siguiente llamada del LLM. Use GetJSONString con un índice incremental (por ejemplo, tool_calls/1/...) para leer cada llamada, y devuelva 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. Arrastre 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. Haga doble clic en la actividad para abrir su configuración.

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

  4. En Choose tool, seleccione el método para especificar la herramienta:

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

  5. Haga clic en Next para revisar el esquema de datos de la herramienta seleccionada y luego haga clic en Finished.

  6. Agregue una transformación a la izquierda de la actividad Invoke Tools. La transformación asigna los valores de argumentos 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. Agregue un paso de script o una transformación después de la actividad para asignar el resultado de la herramienta a function_resp. Pase function_resp al paso de construcción de mensajes en Implementar un bucle de llamada de herramienta del LLM para agregar el resultado a la conversación y desencadenar la siguiente llamada del LLM.

Nota

Si el resultado de la herramienta es datos estructurados (por ejemplo, un objeto JSON), serialícelo a una cadena antes de asignarlo a function_resp. El campo content del mensaje de 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. Utiliza WriteToOperationLog para registrar los nombres de las herramientas y verificar que las herramientas esperadas estén listadas.

  2. Ejecuta una prueba de llamada LLM con el manifiesto de herramientas registrado. Envía un mensaje del usuario que corresponda claramente a 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 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 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 discrepancia 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 adecuadamente.