Skip to content

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

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

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 
      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).