Skip to Content

Connect to an MCP server using the MCP Client connector in Jitterbit Studio

Introduction

The Model Context Protocol (MCP) is an open standard for connecting LLMs to external tools and data sources. An MCP server exposes a collection of named tools, each with a defined input schema. An MCP client discovers those tools, passes their schemas to an LLM as available functions, and executes the tool calls the LLM selects.

The MCP Client connector provides two activities that cover the tool-calling cycle:

  • List Tools: Fetches the tool manifest from the MCP server. Use this to populate the LLM's available tools before each conversation.
  • Invoke Tools: Executes a specific tool on the MCP server with the arguments the LLM selected. Use this after the LLM returns a tool_calls response.

This guide covers connection setup, tool manifest retrieval, and tool invocation at the connector level. For the complete multi-round loop that connects these steps to an LLM, see Implement an LLM tool-calling loop. For a full agent walkthrough that assembles these components into a working AI agent, see How to build an AI agent with MCP.

Design pattern

The MCP tool execution cycle uses two operations. A Tool Discovery operation retrieves the tool manifest once (or at the start of each session) and registers the available tools with the LLM. A Tool Invocation operation runs each time the LLM selects a tool and returns the result to the 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"]
Operation Steps Purpose
Tool Discovery List Tools (source) → Transformation → LLM activity Retrieve the tool manifest from the MCP server and register it with the LLM.
Tool Invocation Transformation (source) → Invoke Tools (target) Execute the tool the LLM selected and capture the result.

Part 1: Configure the MCP Client connection

  1. In the project designer, open the Project endpoints and connectors tab of the design component palette.

  2. Under Available endpoints, click MCP Client to expand it and show the available activity types.

  3. Click Add New Endpoint to create a new connection. The connection configuration screen opens.

  4. Enter a Connection name. The name must be unique within the project and must not contain / or :.

  5. In MCP server URL, enter the full endpoint URL of the MCP server, including the protocol and path. For example, https://api.example.com/mcp.

  6. Under Authentication mechanism, select the option that matches the MCP server:

    • No Auth: No credentials are required.
    • Access Token: Enter a Bearer token issued by the MCP server or its service provider.
    • Authorization Code Grant: Select an OAuth application configured in App Registrations and click Log in with OAuth. See the 3LO prerequisites for setup requirements. Agent version 10.83 / 11.21 or later is required.

  7. (Optional) Click Optional settings to configure additional settings:

    • Protocol Version: Select the MCP protocol version. The default (2025-06-18) is recommended unless the MCP server requires a specific version.
    • Timeout (in milliseconds): Increase this value if the MCP server is slow to respond. The default is 30000 (30 seconds).
    • Custom Request Headers: Add any headers the server requires on every request.

  8. Click Test to verify the connection. A successful test also downloads the latest connector version to the agent group assigned to the current environment.

  9. Click Save Changes.

Note

When you test the connection, the connector stores any session ID the MCP server returns in the response headers and includes it in all subsequent requests automatically. You do not need to add the session ID as a custom request header.

Part 2: Retrieve the tool manifest

The List Tools activity retrieves all tools currently registered on the MCP server. Each tool entry includes its name, description, and input schema. Run this operation before the first LLM call in a workflow, or at the start of each session if the server's tool set changes dynamically.

  1. Drag the List Tools activity type from the design component palette to a drop zone on the design canvas. A new operation is created.

  2. Double-click the activity to open its configuration.

  3. In the Name field, enter a name for the activity (for example, MCP - List Tools).

  4. Click Next to proceed to Step 2, where the response schema returned by the MCP server is displayed. Click Refresh if the schema does not appear.

  5. Click Finished.

  6. Add a transformation to the right of the List Tools activity in the same operation. The transformation maps the MCP tool definitions to the format expected by the LLM. See Part 3 for the mapping details.

Part 3: Map the tool manifest to the LLM format

The List Tools response includes a tools array. Each entry contains the following fields:

MCP field Type Description
name String The tool's unique identifier, used in tool_calls responses and as the input to the Invoke Tools activity.
description String A plain-language description the LLM uses to decide when to call the tool.
inputSchema Object A JSON Schema object describing the tool's required and optional parameters.

Most LLM APIs, including OpenAI Chat Completions and Azure OpenAI, expect tools passed as function schemas:

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

In the transformation after List Tools, map name, description, and inputSchema to the corresponding fields in the LLM's request schema. If you are using an LLM connector (for example, OpenAI or Amazon Bedrock) that provides a Register Tools activity, place that activity to the right of the transformation as the target of the operation.

When the operation runs, Jitterbit stores the registered tool schemas in memory on the private agent. Any operation chained to run after this one automatically has access to those schemas when it calls the LLM. You do not need to capture the Register Tools response or pass the tool definitions explicitly to the subsequent Prompt operation. This in-memory storage is a private agent capability, which is why a private agent is required to use the Register Tools activity.

Note

The private agent requirement above applies to the classic Register Tools activity, which holds tool schemas in agent memory. The OpenAI connector's newer Register Tools V2 and Register MCP Server Tools activities (used with the Prompt V2 activity) also support cloud agent groups: enable Store chat context across operations in the OpenAI connection to retain the registered tools and conversation across operations that share the same chatId.

Tip

Only one Register Tools operation is needed per workflow run. The Prompt operation does not need a tool manifest included in its request. Jitterbit supplies the stored schemas from agent memory automatically.

If you are calling the LLM using the HTTP v2 connector, include the serialized tool array in the tools field of the LLM request body. Store the result as a project variable (for example, mcp_tools_json) so it can be reused in each LLM request without calling List Tools again. For LLM request body construction and HTTP v2 call setup, see Call a REST API using the HTTP v2 connector.

Part 4: Invoke a tool on the MCP server

When the LLM returns a tool_calls response, extract the tool name and arguments, then execute the tool using the Invoke Tools activity.

Extract the tool call from the LLM response

After the LLM call, add a script step to read the response and set the tool call variables:

$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 must exactly match the name value returned by List Tools and defined on the MCP server. function_args is a JSON string containing the parameter values the LLM selected. Parse it using JSONParser to extract individual values before passing them to the transformation in the next step.

Handling multiple tool calls

The script above reads tool_calls/0, the first tool call in the response. An LLM can return several tool calls in a single response (parallel tool calls), and any calls after the first are ignored by this script. To handle every call, do one of the following:

  • Disable parallel tool calls in the LLM request so the model returns at most one call per response. For the OpenAI and Azure OpenAI Chat Completions APIs, set parallel_tool_calls to false in the request body.
  • Iterate over the tool_calls array, invoking the tool and appending a tool result message for each entry before the next LLM call. Use GetJSONString with an incrementing index (for example, tool_calls/1/...) to read each call, and return one tool message per tool_call_id. The LLM API requires a matching tool result for every tool_call_id in the assistant message.

Configure the Invoke Tools activity

  1. Drag the Invoke Tools activity type from the design component palette to a drop zone on the design canvas.

  2. Double-click the activity to open its configuration.

  3. In the Name field, enter a name for the activity (for example, MCP - Invoke Tool).

  4. Under Choose tool, select the method for specifying the tool:

    • Inform tool name manually: Enter [function_name] in the Tool name field. This passes the variable holding the LLM-selected tool name at runtime, allowing a single activity instance to invoke any tool on the MCP server.
    • Select tool from list: Choose a specific tool from the list at design time. Use this approach when the operation is dedicated to one known tool.

  5. Click Next to review the data schema for the selected tool, then click Finished.

  6. Add a transformation to the left of the Invoke Tools activity. The transformation maps the argument values extracted from function_args to the input fields defined in the tool's inputSchema. The schema is specific to the selected tool and is available in the activity's Step 2.

Capture the tool result

After the Invoke Tools activity executes, the MCP server's response is available through the activity's data schema. Add a script step or transformation after the activity to assign the tool result to function_resp. Pass function_resp to the message-building step in Implement an LLM tool-calling loop to append the result to the conversation and trigger the next LLM call.

Note

If the tool result is structured data (for example, a JSON object), serialize it to a string before assigning it to function_resp. The tool role message content field in the LLM API requires a string value.

Verify the integration

  1. Deploy and run the Tool Discovery operation. In the operation logs, confirm that the List Tools activity returned a non-empty manifest. Use WriteToOperationLog to log tool names and verify that the expected tools are listed.

  2. Run a test LLM call with the tool manifest registered. Send a user message that clearly corresponds to one of the registered tools. Confirm in the logs that the LLM response contains a tool_calls entry and that function_name matches a tool name from the manifest.

  3. Deploy and run the Tool Invocation operation with function_name and function_args set to a valid tool call. Verify in the logs that the Invoke Tools activity completed and that function_resp contains the expected output from the MCP server.

  4. If the Invoke Tools activity fails with a schema error, click Refresh in the activity's Step 2 to regenerate the schema from the MCP server, then review the transformation mapping.

  5. If the LLM selects a tool that is not available on the MCP server (for example, due to a name mismatch), the Invoke Tools activity returns an error. Enable Continue on error in the activity configuration to log the error without stopping the operation, then return a descriptive error message to the LLM as the tool result so the model can respond appropriately.