Skip to main content

Call Tool

Calls a tool on an MCP server with specified arguments and returns the result. This node enables your automation to execute functions exposed by MCP servers.

Common Properties​

  • Name - The custom name of the node.
  • Color - The custom color of the node.
  • Delay Before (sec) - Waits in seconds before executing the node.
  • Delay After (sec) - Waits in seconds after executing node.
  • Continue On Error - Automation will continue regardless of any error. The default value is false.
info

If the ContinueOnError property is true, no error is caught when the project is executed, even if a Catch node is used.

Inputs​

  • Client Id - The MCP client connection identifier from the Connect node. Identifies which server to call the tool on.
  • Tool Name - The name of the tool to execute on the MCP server.
  • Arguments - JSON object containing the arguments to pass to the tool. Must match the tool's input schema.

Options​

  • Timeout - Timeout in seconds for the tool call (default: 60). Increase for long-running tools.

Outputs​

  • Response - The result returned by the tool, formatted as a JSON string. Contains a content array with the tool's output.

How It Works​

The Call Tool node executes a tool on an MCP server:

  1. Client Lookup - Retrieves the MCP client using the provided Client ID
  2. Argument Processing - Converts arguments to the proper format (supports JSON string, object, or map)
  3. Request Creation - Creates an MCP CallToolRequest with the tool name and arguments
  4. Tool Execution - Sends the request to the MCP server and waits for response
  5. Response Processing - Extracts content from the response (text or image content)
  6. JSON Formatting - Converts the result to JSON format for output

The response contains a content array where each item has:

  • type: Content type (text or image)
  • text: Text content (for text responses)
  • data/mimeType: Image data (for image responses)

Requirements​

  • Valid Client ID from a Connect node
  • Non-empty Tool Name
  • Arguments that match the tool's JSON schema
  • Active connection to the MCP server

Error Handling​

The node returns specific errors:

  • ErrInvalidArg - Client ID or Tool Name is empty, or arguments are invalid
  • ErrMCPToolCall - Tool execution failed on the server

Usage Notes​

Arguments Format​

The Arguments input accepts multiple formats:

  • JSON Object: {"location": "Paris, France", "unit": "celsius"}
  • JSON String: '{"location": "Paris, France"}'
  • Message Variable: msg.tool_args

Response Structure​

The Response output is a JSON string with this structure:

{
  "content": [
    {
      "type": "text",
      "text": "Tool result here"
    }
  ]
}

For image responses:

{
  "content": [
    {
      "type": "image",
      "data": "base64_encoded_data",
      "mimeType": "image/png"
    }
  ]
}

Timeout Considerations​

  • Default timeout is 60 seconds
  • Increase for computationally intensive tools
  • Decrease for simple, fast tools
  • Server-side timeouts may also apply

Examples​

Example 1: Get Weather​

Inputs:

  • Client Id: weather-server
  • Tool Name: get_weather
  • Arguments:
{
  "location": "Tokyo, Japan",
  "unit": "celsius"
}

Response:

{
  "content": [
    {
      "type": "text",
      "text": "{\"temperature\": 22, \"conditions\": \"sunny\", \"humidity\": 65}"
    }
  ]
}

Example 2: Database Query​

Inputs:

  • Client Id: db-server
  • Tool Name: query_database
  • Arguments:
{
  "query": "SELECT * FROM users WHERE role = 'admin'",
  "limit": 10
}

Response:

{
  "content": [
    {
      "type": "text",
      "text": "[{\"id\": 1, \"name\": \"Alice\"}, {\"id\": 2, \"name\": \"Bob\"}]"
    }
  ]
}

Example 3: Send Email​

Inputs:

  • Client Id: email-server
  • Tool Name: send_email
  • Arguments:
{
  "to": "user@example.com",
  "subject": "Automation Report",
  "body": "Your daily report is ready.",
  "priority": "normal"
}

Response:

{
  "content": [
    {
      "type": "text",
      "text": "{\"success\": true, \"message_id\": \"msg_123abc\"}"
    }
  ]
}

Inputs:

  • Client Id: filesystem
  • Tool Name: search_files
  • Arguments:
{
  "path": "/documents",
  "pattern": "*.pdf",
  "max_results": 20
}

Options:

  • Timeout: 30

Response:

{
  "content": [
    {
      "type": "text",
      "text": "[\"report.pdf\", \"invoice.pdf\", \"manual.pdf\"]"
    }
  ]
}

Example 5: Image Generation​

Inputs:

  • Client Id: image-server
  • Tool Name: generate_image
  • Arguments:
{
  "prompt": "A sunset over mountains",
  "size": "1024x1024"
}

Options:

  • Timeout: 120

Response:

{
  "content": [
    {
      "type": "image",
      "data": "iVBORw0KGgoAAAANS...",
      "mimeType": "image/png"
    }
  ]
}

Best Practices​

  1. Tool Discovery:

    • Use List Tools node first to discover available tools
    • Verify tool name spelling matches exactly
    • Check tool schemas for required arguments

  2. Argument Validation:

    • Ensure arguments match tool's JSON schema
    • Provide all required parameters
    • Use correct data types (string, number, boolean, etc.)

  3. Error Handling:

    • Always handle potential errors (Continue On Error or Catch node)
    • Check response for error messages
    • Validate Client ID before calling tools

  4. Timeout Management:

    • Set appropriate timeouts based on tool complexity
    • Don't set unnecessarily long timeouts
    • Handle timeout errors gracefully

  5. Response Processing:

    • Parse JSON response to extract actual data
    • Handle both text and image content types
    • Check for error indicators in response

  6. Performance:

    • Reuse Client ID across multiple tool calls
    • Batch operations when possible
    • Cache results if appropriate

Common Errors and Solutions​

Error: "Client Id cannot be empty"​

Cause: Client ID input is missing or empty.

Solution:

  • Connect Client Id from a Connect node
  • Verify Connect node executed successfully
  • Check Client Id is being passed correctly

Error: "Tool Name cannot be empty"​

Cause: Tool Name input is missing or empty.

Solution:

  • Provide a valid tool name
  • Use List Tools to discover available tools
  • Check spelling matches exactly

Error: "MCP client not found"​

Cause: No client exists with the provided Client ID.

Solution:

  • Ensure Connect node executed before Call Tool
  • Verify Client ID is correct
  • Check connection didn't fail or close

Error: "Failed to call tool"​

Cause: Tool execution failed on the server.

Solution:

  • Check arguments match tool schema
  • Verify all required arguments are provided
  • Check server logs for detailed error
  • Ensure tool exists on the server

Error: "Failed to parse arguments"​

Cause: Arguments are not in valid JSON format.

Solution:

  • Validate JSON syntax
  • Ensure proper quote escaping
  • Use object notation instead of string when possible

Tips for Effective Use​

  1. List Tools First - Use List Tools to discover available tools and their schemas
  2. Validate Arguments - Ensure arguments match the tool's expected schema
  3. Handle Errors - Always implement error handling for tool calls
  4. Parse Responses - Extract data from the JSON response structure
  5. Set Timeouts - Configure appropriate timeouts based on tool complexity
  6. Test Incrementally - Test with simple tools first
  7. Log Results - Log responses for debugging and monitoring

Response Parsing Example​

// In a JavaScript node after Call Tool
const response = JSON.parse(msg.response);

// Extract text content
if (response.content && response.content.length > 0) {
  const firstContent = response.content[0];

  if (firstContent.type === 'text') {
    // Parse the text content (often JSON)
    const result = JSON.parse(firstContent.text);
    msg.tool_result = result;
  } else if (firstContent.type === 'image') {
    // Handle image content
    msg.image_data = firstContent.data;
    msg.image_mime_type = firstContent.mimeType;
  }
}

Integration Patterns​

Pattern 1: Single Tool Call​

Connect → Call Tool → Process Response

Pattern 2: Sequential Tool Calls​

Connect → Call Tool 1 → Call Tool 2 → Call Tool 3 → Combine Results

Pattern 3: Conditional Tool Calls​

Connect → List Tools → Filter → Call Tool (if available)

Pattern 4: Error Handling​

Connect → Try → Call Tool → Success Handler
           ↓
         Catch → Error Handler

Pattern 5: Parallel Tool Calls​

Connect → Split → Call Tool A
                → Call Tool B → Merge Results
                → Call Tool C