Module: MCPClient

Defined in:
lib/mcp_client.rb,
lib/mcp_client/auth.rb,
lib/mcp_client/tool.rb,
lib/mcp_client/client.rb,
lib/mcp_client/errors.rb,
lib/mcp_client/prompt.rb,
lib/mcp_client/version.rb,
lib/mcp_client/resource.rb,
lib/mcp_client/server_sse.rb,
lib/mcp_client/server_base.rb,
lib/mcp_client/server_http.rb,
lib/mcp_client/oauth_client.rb,
lib/mcp_client/server_stdio.rb,
lib/mcp_client/config_parser.rb,
lib/mcp_client/server_factory.rb,
lib/mcp_client/json_rpc_common.rb,
lib/mcp_client/resource_content.rb,
lib/mcp_client/resource_template.rb,
lib/mcp_client/auth/oauth_provider.rb,
lib/mcp_client/http_transport_base.rb,
lib/mcp_client/server_sse/sse_parser.rb,
lib/mcp_client/server_streamable_http.rb,
lib/mcp_client/server_sse/reconnect_monitor.rb,
lib/mcp_client/server_sse/json_rpc_transport.rb,
lib/mcp_client/server_http/json_rpc_transport.rb,
lib/mcp_client/server_stdio/json_rpc_transport.rb,
lib/mcp_client/server_streamable_http/json_rpc_transport.rb

Overview

Model Context Protocol (MCP) Client module Provides a standardized way for agents to communicate with external tools and services through a protocol-based approach

Defined Under Namespace

Modules: Auth, Errors, HttpTransportBase, JsonRpcCommon Classes: Client, ConfigParser, OAuthClient, Prompt, Resource, ResourceContent, ResourceTemplate, ServerBase, ServerFactory, ServerHTTP, ServerSSE, ServerStdio, ServerStreamableHTTP, Tool

Constant Summary collapse

VERSION =

Current version of the MCP client gem

'0.8.1'
PROTOCOL_VERSION =

MCP protocol version (date-based) - unified across all transports

'2025-03-26'

Class Method Summary collapse

Class Method Details

.create_client(mcp_server_configs: [], server_definition_file: nil, logger: nil) ⇒ MCPClient::Client

Create a new MCPClient client

Parameters:

  • mcp_server_configs (Array<Hash>) (defaults to: []) —

    configurations for MCP servers

  • server_definition_file (String, nil) (defaults to: nil) —

    optional path to a JSON file defining server configurations The JSON may be a single server object or an array of server objects.

  • logger (Logger, nil) (defaults to: nil) —

    optional logger for client operations

Returns:



32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
 
# File 'lib/mcp_client.rb', line 32

def self.create_client(mcp_server_configs: [], server_definition_file: nil, logger: nil)
  require 'json'
  # Start with any explicit configs provided
  configs = Array(mcp_server_configs)
  # Load additional configs from a JSON file if specified
  if server_definition_file
    # Parse JSON definitions into clean config hashes
    parser = MCPClient::ConfigParser.new(server_definition_file, logger: logger)
    parsed = parser.parse
    parsed.each_value do |cfg|
      case cfg[:type].to_s
      when 'stdio'
        cmd_list = [cfg[:command]] + Array(cfg[:args])
        configs << MCPClient.stdio_config(
          command: cmd_list,
          name: cfg[:name],
          logger: logger,
          env: cfg[:env]
        )
      when 'sse'
        configs << MCPClient.sse_config(base_url: cfg[:url], headers: cfg[:headers] || {}, name: cfg[:name],
                                        logger: logger)
      when 'http'
        configs << MCPClient.http_config(base_url: cfg[:url], endpoint: cfg[:endpoint],
                                         headers: cfg[:headers] || {}, name: cfg[:name], logger: logger)
      when 'streamable_http'
        configs << MCPClient.streamable_http_config(base_url: cfg[:url], endpoint: cfg[:endpoint],
                                                    headers: cfg[:headers] || {}, name: cfg[:name], logger: logger)
      end
    end
  end
  MCPClient::Client.new(mcp_server_configs: configs, logger: logger)
end

.http_config(base_url:, endpoint: '/rpc', headers: {}, read_timeout: 30, retries: 3, retry_backoff: 1, name: nil, logger: nil) ⇒ Hash

Create a standard server configuration for HTTP

Parameters:

  • base_url (String) —

    base URL for the server

  • endpoint (String) (defaults to: '/rpc') —

    JSON-RPC endpoint path (default: ‘/rpc’)

  • headers (Hash) (defaults to: {}) —

    HTTP headers to include in requests

  • read_timeout (Integer) (defaults to: 30) —

    read timeout in seconds (default: 30)

  • retries (Integer) (defaults to: 3) —

    number of retry attempts (default: 3)

  • retry_backoff (Integer) (defaults to: 1) —

    backoff delay in seconds (default: 1)

  • name (String, nil) (defaults to: nil) —

    optional name for this server

  • logger (Logger, nil) (defaults to: nil) —

    optional logger for server operations

Returns:

  • (Hash) —

    server configuration



116
117
118
119
120
121
122
123
124
125
126
127
128
129
 
# File 'lib/mcp_client.rb', line 116

def self.http_config(base_url:, endpoint: '/rpc', headers: {}, read_timeout: 30, retries: 3, retry_backoff: 1,
                     name: nil, logger: nil)
  {
    type: 'http',
    base_url: base_url,
    endpoint: endpoint,
    headers: headers,
    read_timeout: read_timeout,
    retries: retries,
    retry_backoff: retry_backoff,
    name: name,
    logger: logger
  }
end

.sse_config(base_url:, headers: {}, read_timeout: 30, ping: 10, retries: 0, retry_backoff: 1, name: nil, logger: nil) ⇒ Hash

Create a standard server configuration for SSE

Parameters:

  • base_url (String) —

    base URL for the server

  • headers (Hash) (defaults to: {}) —

    HTTP headers to include in requests

  • read_timeout (Integer) (defaults to: 30) —

    read timeout in seconds (default: 30)

  • ping (Integer) (defaults to: 10) —

    time in seconds after which to send ping if no activity (default: 10)

  • retries (Integer) (defaults to: 0) —

    number of retry attempts (default: 0)

  • retry_backoff (Integer) (defaults to: 1) —

    backoff delay in seconds (default: 1)

  • name (String, nil) (defaults to: nil) —

    optional name for this server

  • logger (Logger, nil) (defaults to: nil) —

    optional logger for server operations

Returns:

  • (Hash) —

    server configuration



91
92
93
94
95
96
97
98
99
100
101
102
103
104
 
# File 'lib/mcp_client.rb', line 91

def self.sse_config(base_url:, headers: {}, read_timeout: 30, ping: 10, retries: 0, retry_backoff: 1,
                    name: nil, logger: nil)
  {
    type: 'sse',
    base_url: base_url,
    headers: headers,
    read_timeout: read_timeout,
    ping: ping,
    retries: retries,
    retry_backoff: retry_backoff,
    name: name,
    logger: logger
  }
end

.stdio_config(command:, name: nil, logger: nil, env: {}) ⇒ Hash

Create a standard server configuration for stdio

Parameters:

  • command (String, Array<String>) —

    command to execute

  • name (String, nil) (defaults to: nil) —

    optional name for this server

  • logger (Logger, nil) (defaults to: nil) —

    optional logger for server operations

Returns:

  • (Hash) —

    server configuration



71
72
73
74
75
76
77
78
79
 
# File 'lib/mcp_client.rb', line 71

def self.stdio_config(command:, name: nil, logger: nil, env: {})
  {
    type: 'stdio',
    command: command,
    name: name,
    logger: logger,
    env: env || {}
  }
end

.streamable_http_config(base_url:, endpoint: '/rpc', headers: {}, read_timeout: 30, retries: 3, retry_backoff: 1, name: nil, logger: nil) ⇒ Hash

Create configuration for Streamable HTTP transport This transport uses HTTP POST requests but expects Server-Sent Event formatted responses

Parameters:

  • base_url (String) —

    Base URL of the MCP server

  • endpoint (String) (defaults to: '/rpc') —

    JSON-RPC endpoint path (default: ‘/rpc’)

  • headers (Hash) (defaults to: {}) —

    Additional headers to include in requests

  • read_timeout (Integer) (defaults to: 30) —

    Read timeout in seconds (default: 30)

  • retries (Integer) (defaults to: 3) —

    Number of retry attempts on transient errors (default: 3)

  • retry_backoff (Integer) (defaults to: 1) —

    Backoff delay in seconds (default: 1)

  • name (String, nil) (defaults to: nil) —

    Optional name for this server

  • logger (Logger, nil) (defaults to: nil) —

    Optional logger for server operations

Returns:

  • (Hash) —

    server configuration



142
143
144
145
146
147
148
149
150
151
152
153
154
155
 
# File 'lib/mcp_client.rb', line 142

def self.streamable_http_config(base_url:, endpoint: '/rpc', headers: {}, read_timeout: 30, retries: 3,
                                retry_backoff: 1, name: nil, logger: nil)
  {
    type: 'streamable_http',
    base_url: base_url,
    endpoint: endpoint,
    headers: headers,
    read_timeout: read_timeout,
    retries: retries,
    retry_backoff: retry_backoff,
    name: name,
    logger: logger
  }
end