MCP Client Agent¶

The MCPClientAgent in the AI Refinery SDK is designed to integrate Model Context Protocol (MCP) support into the AI Refinery. This agent enables dynamic discovery and invoking external tools exposed by MCP servers over Server-Sent Events (SSE). Here, an MCP server acts as middleware that exposes tools and services through a unified API for real-time discovery and invocation—check MCP server introduction for details. In addition, we have provided some popular MCP servers—check MCP server catalog.

Workflow Overview¶

Being a Utility Agent, the MCPClientAgent can be invoked either directly by the orchestrator or by a Super Agent. Its capabilities include:

Tool Discovery: Connects to MCP servers to retrieve available tools, resources, and prompts.
Tool Invocation: Interprets user queries to determine appropriate tool usage and executes them via the MCP server.
Optional Output Interpretation: Utilizes an optional interpreter agent to process and refine tool outputs for natural language format responses.

Usage¶

The MCPClientAgent can be readily integrated into a project by adding the required configuration in the project's YAML file. The agent needs to be listed under the available Utility Agents and then can be selected by the orchestrator or its corresponding Super Agent

Quickstart¶

To quickly set up a project with an MCPClientAgent, you first need to make sure that the MCP server that the agent will connect to is running. If that server is running locally, you need to make sure you expose the server over a certain port through SSE. Then, you can use the following YAML configuration template to allow the agent to connect to the server and utilize its tools.

orchestrator:
  agent_list:
    - agent_name: "Filesystem Agent"  # Agent for performing filesystem operations
    - agent_name: "Python Executor Agent"  # Agent for executing Python code snippets
    - agent_name: "Google Calendar Agent"  # Agent for managing Google Calendar events
    - agent_name: "Travelling Tips Advisor" # Agent for providing Travelling tips

utility_agents:
  - agent_class: MCPClientAgent
    agent_name: "Filesystem Agent"  # Should match the agent_name in orchestrator
    agent_description: "Performs filesystem operations (such as listing files and reading file content, etc) from a specific directory." # Description of functionality
    config:
      mcp_sse_url: "http://localhost:4001/sse"  # User defined local URL of the MCP server exposing filesystem services
      enable_interpreter: false # Optional: Disables output interpretation. If set to false, the agent will directly return JSON send back from MCP server.
      wait_time: 260 #  Optional: Time (in seconds) the agent waits for MCP server response

  - agent_class: MCPClientAgent
    agent_name: "Python Executor Agent"  # Should match the agent_name in orchestrator
    agent_description: "Executes simple Python code snippets safely." # Description of functionality
    config:
      mcp_sse_url: "http://localhost:4002/sse"  # User defined local URL of the MCP server providing Python execution sandbox
      enable_interpreter: false # Optional: Disables output interpretation. If set to false, the agent will directly return JSON send back from MCP server.
      wait_time: 820 #  Optional: Time (in seconds) the agent waits for MCP server response

  - agent_class: MCPClientAgent
    agent_name: "Google Calendar Agent"  # Should match the agent_name in orchestrator
    agent_description: "Handles Google Calendar scheduling tasks." # Description of functionality
    config:
      mcp_sse_url: "http://localhost:4003/sse"  # User defined local URL of the MCP server providing Google Calendar services
      enable_interpreter: true # Optional: Enables output interpretation. If set to true, the agent will convert the returned message JSON into a natural language response.
      # If not set wait_time then use Default AIR_CONFIG.AGENT_TIMEOUT Time (300 seconds) the agent waits for MCP server response

  - agent_class: MCPClientAgent
    agent_name: "Travelling Tips Advisor" # Should match the agent_name in orchestrator
    agent_description: "Provide travel tips on visa policies and weather conditions." # Description of functionality
    config:
      mcp_sse_url: "http://localhost:4004/sse" # duckduckgo MCP server
      enable_interpreter: true # Optional: Enables output interpretation. If set to true, the agent will convert the returned message JSON into a natural language response.
      wait_time: 1000 # Optional: Time (in seconds) the agent waits for MCP server response
      tool_call_interval: 3  # Optional: Add time interval (seconds) between tool calls to avoid bot detection.
      max_tool_calls: 2  # Optional: Add limitations in maximum number of tool calls. This is consistent with magic_prompt for searching visa / weahter information
      show_tool_progress: True # Optional: Display tool call waiting signal 
      llm_config:  # Optional inherit from UtilityAgent : Change LLM modal for current agent best for MCP calling performance
        model: "Qwen/Qwen3-32B" # Default is Llama-3.1-70B
      magic_prompt: | # Optional inherit from UtilityAgent: Overwrite the agent prmopt for specific task requirement.
        Your task is to provide the user's travel tips with help **Must** from calling MCP tools.

        Instructions:
        1. Figure out the tools available to you.
        2. Clearly interpret the user's request and craft human-like, straightforward queries separately to search:
          a. visa requirements (eg. Japan visa policy)
          b. weather at the time (eg. Winter/Summer in Tokyo)
        3. Determine which tool(s) to use and gather the necessary information.
        4. Limit the websearch response number range to 3.

        [ Query ]
        {query}

Template YAML Configuration of `MCPClientAgent`¶

In this setup, we have a single MCP Client agent that is made available to the orchestrator.

orchestrator:
  agent_list:
    - agent_name: <Name of the Agent>  # The characteristic name of the agent

utility_agents:
  - agent_class: MCPClientAgent
    agent_name: <Name of the Agent>  # The name of the agent that needs to coincide with the one listed under the orchestrator
    agent_description: <Description of the Agent>  # Description of functionality
    config:
      mcp_sse_url: "http://localhost:<PORT>/sse"  # URL specifying the port where the MCP server is exposed for the agent to connect to 
      tool_call_interval: 3  # Optional: Add time interval (seconds) between tool calls to avoid bot detection for external api calling (such as websearch). Default is 1 second.
      max_tool_calls: 2  # Optional: Add limitations in maximum number of tool calls. Default is 5.
      show_tool_progress: True # # Optional: Display tool call waiting signal 
      enable_interpreter: false # Optional: Switch to enable the optional output interpretation, if not set then defaults to false.
      wait_time: 300 # Optional: Time that the agent waits for a response from the MCP server, if not set use  Default AIR_CONFIG.AGENT_TIMEOUT Time (in seconds).

MCP Client Agent¶

Workflow Overview¶

Usage¶

Quickstart¶

Template YAML Configuration of MCPClientAgent¶

Template YAML Configuration of `MCPClientAgent`¶