Add basic HTTP client support with pluggable transports

Author: jcat4

Gemfile

@@ -6,9 +6,6 @@ source "https://rubygems.org"
 gemspec
 
 # Specify development dependencies below
-gem "minitest", "~> 5.1", require: false
-gem "mocha"
-
 gem "rubocop-minitest", require: false
 gem "rubocop-rake", require: false
 gem "rubocop-shopify", require: false
@@ -21,3 +18,10 @@ gem "activesupport"
 gem "debug"
 gem "rake", "~> 13.0"
 gem "sorbet-static-and-runtime"
+
+group :test do
+  gem "faraday", ">= 2.0"
+  gem "minitest", "~> 5.1", require: false
+  gem "mocha"
+  gem "webmock"
+end

README.md

@@ -22,7 +22,9 @@ Or install it yourself as:
 $ gem install mcp
 ```
 
-## MCP Server
+You may need to add additional dependencies depending on which features you wish to access.
+
+## Building an MCP Server
 
 The `MCP::Server` class is the core component that handles JSON-RPC requests and responses.
 It implements the Model Context Protocol specification, handling model context requests and responses.
@@ -216,7 +218,7 @@ $ ruby examples/stdio_server.rb
 {"jsonrpc":"2.0","id":"2","method":"tools/list"}
 ```
 
-## Configuration
+### Configuration
 
 The gem can be configured using the `MCP.configure` block:
 
@@ -363,7 +365,7 @@ When an exception occurs:
 
 If no exception reporter is configured, a default no-op reporter is used that silently ignores exceptions.
 
-## Tools
+### Tools
 
 MCP spec includes [Tools](https://modelcontextprotocol.io/specification/2025-06-18/server/tools) which provide functionality to LLM apps.
 
@@ -428,7 +430,7 @@ Tools can include annotations that provide additional metadata about their behav
 
 Annotations can be set either through the class definition using the `annotations` class method or when defining a tool using the `define` method.
 
-## Prompts
+### Prompts
 
 MCP spec includes [Prompts](https://modelcontextprotocol.io/specification/2025-06-18/server/prompts), which enable servers to define reusable prompt templates and workflows that clients can easily surface to users and LLMs.
 
@@ -554,7 +556,7 @@ The data contains the following keys:
 `tool_name`, `prompt_name` and `resource_uri` are only populated if a matching handler is registered.
 This is to avoid potential issues with metric cardinality
 
-## Resources
+### Resources
 
 MCP spec includes [Resources](https://modelcontextprotocol.io/specification/2025-06-18/server/resources).
 
@@ -590,6 +592,101 @@ end
 
 otherwise `resources/read` requests will be a no-op.
 
+## Building an MCP Client
+
+The `MCP::Client` class provides an interface for interacting with MCP servers.
+Clients are initialized with a transport layer instance that handles the low-level communication mechanics.
+
+## Transport Layer Interface
+
+If the transport layer you need is not included in the gem, you can build and pass your own instances so long as they conform to the following interface:
+
+```ruby
+class CustomTransport
+  # Sends a JSON-RPC request to the server and returns the raw response.
+  #
+  # @param request [Hash] A complete JSON-RPC request object.
+  #     https://www.jsonrpc.org/specification#request_object
+  # @return [Hash] A hash modeling a JSON-RPC response object.
+  #     https://www.jsonrpc.org/specification#response_object
+  def send_request(request:)
+    # Your transport-specific logic here
+    # - HTTP: POST to endpoint with JSON body
+    # - WebSocket: Send message over WebSocket
+    # - stdio: Write to stdout, read from stdin
+    # - etc.
+  end
+end
+```
+
+### HTTP Transport Layer
+
+Use the `MCP::Client::Http` transport to interact with MCP servers using simple HTTP requests.
+
+The HTTP client supports:
+
+- Tool listing via the `tools/list` method
+- Tool invocation via the `tools/call` method
+- Automatic JSON-RPC 2.0 message formatting
+- UUID request ID generation
+- Setting headers for things like authorization
+
+You'll need to add `faraday` as a dependency in order to use the HTTP transport layer:
+
+```ruby
+gem 'mcp'
+gem 'faraday', '>= 2.0'
+```
+
+Example usage:
+
+```ruby
+http_transport = MCP::Client::HTTP.new(url: "https://api.example.com/mcp")
+client = MCP::Client.new(transport: http_transport)
+
+# List available tools
+tools = client.tools
+tools.each do |tool|
+  puts <<~TOOL_INFORMATION
+    Tool: #{tool.name}
+    Description: #{tool.description}
+    Input Schema: #{tool.input_schema}
+  TOOL_INFORMATION
+end
+
+# Call a specific tool
+response = client.call_tool(
+  tool: tools.first,
+  arguments: { message: "Hello, world!" }
+)
+```
+
+#### HTTP Authorization
+
+By default, the HTTP transport layer provides no authentication to the server, but you can provide custom headers if you need authentication. For example, to use Bearer token authentication:
+
+```ruby
+http_transport = MCP::Client::HTTP.new(
+  url: "https://api.example.com/mcp",
+  headers: {
+    "Authorization" => "Bearer my_token"
+  }
+)
+
+client = MCP::Client.new(transport: http_transport)
+client.tools # will make the call using Bearer auth
+```
+
+You can add any custom headers needed for your authentication scheme, or for any other purpose. The client will include these headers on every request.
+
+### Tool Objects
+
+The client provides a wrapper class for tools returned by the server:
+
+- `MCP::Client::Tool` - Represents a single tool with its metadata
+
+This class provide easy access to tool properties like name, description, and input schema.
+
 ## Releases
 
 This gem is published to [RubyGems.org](https://rubygems.org/gems/mcp)

lib/mcp.rb

@@ -22,6 +22,9 @@
 require_relative "mcp/tool/annotations"
 require_relative "mcp/transport"
 require_relative "mcp/version"
+require_relative "mcp/client"
+require_relative "mcp/client/http"
+require_relative "mcp/client/tool"
 
 module MCP
   class << self

lib/mcp/client.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module MCP
+  class Client
+    # Initializes a new MCP::Client instance.
+    #
+    # @param transport [Object] The transport object to use for communication with the server.
+    #   The transport should be a duck type that responds to both `#tools` and `#call_tool`.
+    #   This allows the client to list available tools and invoke tool calls via the transport.
+    #
+    # @example
+    #   transport = MCP::Client::HTTP.new(url: "http://localhost:3000")
+    #   client = MCP::Client.new(transport: transport)
+    #
+    # @note
+    #   The transport does not need to be a specific class, but must implement:
+    #     - #tools
+    #     - #call_tool(tool:, arguments:)
+    def initialize(transport:)
+      @transport = transport
+    end
+
+    # The user may want to access additional transport-specific methods/attributes
+    # So keeping it public
+    attr_reader :transport
+
+    # Returns the list of tools available from the server.
+    # Each call will make a new request – the result is not cached.
+    #
+    # @return [Array<MCP::Client::Tool>] An array of available tools.
+    #
+    # @example
+    #   tools = client.tools
+    #   tools.each do |tool|
+    #     puts tool.name
+    #   end
+    def tools
+      response = transport.send_request(request: {
+        jsonrpc: JsonRpcHandler::Version::V2_0,
+        id: request_id,
+        method: "tools/list",
+      })
+
+      response.dig("result", "tools")&.map do |tool|
+        Tool.new(
+          name: tool["name"],
+          description: tool["description"],
+          input_schema: tool["inputSchema"],
+        )
+      end || []
+    end
+
+    # Calls a tool via the transport layer.
+    #
+    # @param tool [MCP::Client::Tool] The tool to be called.
+    # @param arguments [Object, nil] The arguments to pass to the tool.
+    # @return [Object] The result of the tool call, as returned by the transport.
+    #
+    # @example
+    #   tool = client.tools.first
+    #   result = client.call_tool(tool: tool, arguments: { foo: "bar" })
+    #
+    # @note
+    #   The exact requirements for `arguments` are determined by the transport layer in use.
+    #   Consult the documentation for your transport (e.g., MCP::Client::HTTP) for details.
+    def call_tool(tool:, arguments: nil)
+      response = transport.send_request(request: {
+        jsonrpc: JsonRpcHandler::Version::V2_0,
+        id: request_id,
+        method: "tools/call",
+        params: { name: tool.name, arguments: arguments },
+      })
+
+      response.dig("result", "content")
+    end
+
+    private
+
+    def request_id
+      SecureRandom.uuid
+    end
+
+    class RequestHandlerError < StandardError
+      attr_reader :error_type, :original_error, :request
+
+      def initialize(message, request, error_type: :internal_error, original_error: nil)
+        super(message)
+        @request = request
+        @error_type = error_type
+        @original_error = original_error
+      end
+    end
+  end
+end

lib/mcp/client/http.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module MCP
+  class Client
+    class HTTP
+      attr_reader :url
+
+      def initialize(url:, headers: {})
+        @url = url
+        @headers = headers
+      end
+
+      def send_request(request:)
+        method = request[:method] || request["method"]
+        params = request[:params] || request["params"]
+
+        client.post("", request).body
+      rescue Faraday::BadRequestError => e
+        raise RequestHandlerError.new(
+          "The #{method} request is invalid",
+          { method:, params: },
+          error_type: :bad_request,
+          original_error: e,
+        )
+      rescue Faraday::UnauthorizedError => e
+        raise RequestHandlerError.new(
+          "You are unauthorized to make #{method} requests",
+          { method:, params: },
+          error_type: :unauthorized,
+          original_error: e,
+        )
+      rescue Faraday::ForbiddenError => e
+        raise RequestHandlerError.new(
+          "You are forbidden to make #{method} requests",
+          { method:, params: },
+          error_type: :forbidden,
+          original_error: e,
+        )
+      rescue Faraday::ResourceNotFound => e
+        raise RequestHandlerError.new(
+          "The #{method} request is not found",
+          { method:, params: },
+          error_type: :not_found,
+          original_error: e,
+        )
+      rescue Faraday::UnprocessableEntityError => e
+        raise RequestHandlerError.new(
+          "The #{method} request is unprocessable",
+          { method:, params: },
+          error_type: :unprocessable_entity,
+          original_error: e,
+        )
+      rescue Faraday::Error => e # Catch-all
+        raise RequestHandlerError.new(
+          "Internal error handling #{method} request",
+          { method:, params: },
+          error_type: :internal_error,
+          original_error: e,
+        )
+      end
+
+      private
+
+      attr_reader :headers
+
+      def client
+        require_faraday!
+        @client ||= Faraday.new(url) do |faraday|
+          faraday.request(:json)
+          faraday.response(:json)
+          faraday.response(:raise_error)
+
+          headers.each do |key, value|
+            faraday.headers[key] = value
+          end
+        end
+      end
+
+      def require_faraday!
+        require "faraday"
+      rescue LoadError
+        raise LoadError, "The 'faraday' gem is required to use the MCP client HTTP transport. " \
+          "Add it to your Gemfile: gem 'faraday', '>= 2.0'" \
+          "See https://rubygems.org/gems/faraday for more details."
+      end
+    end
+  end
+end

lib/mcp/client/tool.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module MCP
+  class Client
+    class Tool
+      attr_reader :name, :description, :input_schema
+
+      def initialize(name:, description:, input_schema:)
+        @name = name
+        @description = description
+        @input_schema = input_schema
+      end
+    end
+  end
+end