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 both Streamable HTTP/HTTPS and 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 Streamable HTTP/HTTPS or SSE. Then, you can use the following YAML configuration template to allow the agent to connect to the server and utilize its tools.

Configure the agent connection using the appropriate YAML configuration template:

HTTP Stream Configuration:

config:
  mcpServers:
    server_name:  # A descriptive name for the MCP server
      url: "http://localhost:<PORT>/mcp"  # Or any other custom endpoints
      type: "http-stream"

SSE Configuration:

config:
  mcpServers:
    server_name:  # A descriptive name for the MCP server
      url: "http://localhost:<PORT>/sse"  # Or any other custom endpoints
      type: "sse"

Legacy Configuration (Deprecated): While the following legacy format is still supported, we strongly recommend using the new pattern above:

config:
  mcp_sse_url: "http://localhost:<PORT>/sse"

Once configured, the agent can connect to the server and access its available 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:
      mcpServers:
        filesystem:  # Server name
          url: "http://localhost:4001/sse" # User defined local URL of the MCP server exposing filesystem services
          type: "sse" # User specified connection type, "sse"
      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:
      mcpServers:
        python_executor:  # Server name
          url: "http://localhost:4002/sse" # User defined local URL of the MCP server providing Python execution sandbox
          type: "sse" # User specified connection type, "sse"
      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"  # (Old pattern is still supported) 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:
      mcpServers:
        duckduckgo:  # Server name
          url: "http://localhost:4004/mcp" # duckduckgo MCP server
          type: "http-stream" # User specified connection type, "http-stream" for Streamable HTTP/HTTPS
      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. 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
      llm_config:  # Optional inherit from UtilityAgent : Change LLM modal for current agent best for MCP calling performance
        model: "Qwen/Qwen3-32B" # Default is `openai/gpt-oss-120b`.
      magic_prompt: | # Optional inherit from UtilityAgent: Overwrite the agent prompt 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:
      mcpServers:
        <SERVER_NAME>:  # A descriptive name for the MCP server
          url: "http://localhost:<PORT>/<ENDPOINT>"  # URL specifying the port where the MCP server is exposed for the agent to connect to
          type: "<CONNECTION_TYPE>"  # Either "http-stream" or "sse"
      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`¶