groq_ruby 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e37b875bee74a1cd5660dd886ae8aa670b964cd6f75822abf9d66c81060e6b81
-  data.tar.gz: a68e3933724ff8972efef22ab22ea3e5ceb1a657e29451008770c2f63f479068
+  metadata.gz: 9f61d7fe590a9389b584b1d6f6a30551809aa980204401ec03189c7fb468c4d9
+  data.tar.gz: d08fa9af8238213284d457d3b234aa706f1aba45ca99c22edd5b21d61fbeef13
 SHA512:
-  metadata.gz: a97a4e32dae7e9d313da6d6f4dd75e570218f55296e2daf06c071c11230e90e75832ec646f5e6e3f4cdb92e8eaa687235bd9541d20b2e96c7d3a10b6bf9bdea1
-  data.tar.gz: a83b33d635b1b06ff1e157a21d3c9c317ca4bbb0d0793eb575277f1cf1b6750f0fdb8e28540d8d961e123995a223e99d380d15020f3d33967ecdfa372cac9cfe
+  metadata.gz: c7cfbecd253877f1a17b0e688d2b48b4e9a96e04eda485843e4403d254b685643222d29405bae9e9b5d938a887ee301de958ffd4454557d9d766411c27c721fe
+  data.tar.gz: 71c6dad9a48dbc928f31feb545038e4df06cb8e44f7f734a62b3d791ae8a5edf1c9ce0c828af9b9c03ade06848137587c7b40e51d9938f69b961ad67ced1ff5e

data/CHANGELOG.md

@@ -6,6 +6,55 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0]
+
+Adds HTTP-based MCP transport support and per-protocol-version selection,
+so Groq agents can talk to remote MCP servers (HTTP/HTTPS) in addition
+to local stdio-launched ones.
+
+### Added — MCP
+
+- `GroqRuby::MCP::HttpServerConfig` — describes a remote MCP server
+  (URL + extra headers, e.g. for bearer auth). Sibling of `ServerConfig`.
+- `GroqRuby::MCP::Transports::HttpStreamable` — implements the MCP
+  HTTP Streamable transport (single endpoint POST with JSON or SSE
+  response, `Mcp-Session-Id` header captured and echoed,
+  `MCP-Protocol-Version` header on every request, best-effort `DELETE`
+  on `stop`). Each request runs on a background thread; `stop` joins
+  all in-flight threads before terminating the session.
+- `GroqRuby::MCP::Protocol` — registry of versioned protocol objects
+  with `Protocol.for(version)`, `Protocol.default`. Each protocol
+  object owns its `initialize` payload shape and version string.
+- `GroqRuby::MCP::Protocol::V2024_11_05` — original public release
+  protocol (the pre-existing default for stdio servers).
+- `GroqRuby::MCP::Protocol::V2025_11_25` — capability stub for the
+  newest spec; future PRs will add the tasks API surface.
+- `Client.new` and `Client.connect` accept a `protocol:` kwarg.
+  `Client#protocol` exposes the active protocol object.
+- `Client.connect` now dispatches the transport by config type:
+  `ServerConfig` → stdio + 2024-11-05, `HttpServerConfig` → HTTP
+  Streamable + 2025-11-25. Both transport choice and protocol are
+  overridable.
+- `Bridge` accepts mixed `ServerConfig` and `HttpServerConfig` arrays
+  transparently — no API change required.
+- New example: `examples/mcp_http_remote.rb`.
+
+### Changed
+
+- `Client.connect` signature: gained `protocol:` kwarg (default `nil`,
+  resolved from config type). Existing callers passing only a stdio
+  `ServerConfig` are unaffected.
+
+### Notes
+
+- HTTP transport currently lacks the long-lived `GET` SSE channel for
+  server-initiated notifications without an in-flight request; that
+  arrives with the tasks-API follow-up. Server-initiated frames
+  interleaved on a `POST` SSE response are dispatched normally.
+- Sticking with `MCP::PROTOCOL_VERSION = "2024-11-05"` as the
+  top-level constant for backward compatibility; per-instance protocol
+  selection is the forward-compatible API.
+
 ## [0.1.0]
 
 Initial release. Idiomatic Ruby client for the Groq API, mirroring the

data/CLAUDE.md

@@ -52,6 +52,16 @@ explicit discussion:
   feature. The bridge speaks JSON-RPC 2.0 to MCP servers and converts
   their tools to OpenAI-shaped function tools. Don't suggest adding a
   request-side `mcp_servers:` parameter — Groq's API doesn't accept one.
+- **MCP transports are pluggable; protocol versions are pluggable.**
+  `Transports::Stdio` (child process) and `Transports::HttpStreamable`
+  (single HTTPS endpoint) are siblings. `Protocol::V2024_11_05` and
+  `Protocol::V2025_11_25` are sibling protocol objects, each owning the
+  `initialize` payload shape and the version string. `Client.connect`
+  dispatches both transport and default protocol off the config class
+  (`ServerConfig` → stdio + V2024_11_05, `HttpServerConfig` → HTTP +
+  V2025_11_25); both are overridable via the `protocol:` kwarg. Don't
+  consolidate transports into the Client or push protocol-version
+  choice up to a global constant — per-instance is the design.
 
 ## Layout
 
@@ -62,7 +72,9 @@ explicit discussion:
 - `lib/groq_ruby/resources/{chat,audio}/*.rb` and `lib/groq_ruby/resources/*.rb` — one class per API surface.
 - `lib/groq_ruby/models/{chat,audio,embeddings,files,batches}/*.rb` — collapsed → `GroqRuby::Models::*`.
 - `lib/groq_ruby/streaming/*.rb` — SSE adapter (`event_stream_parser`) + `ChunkStream` enumerable.
-- `lib/groq_ruby/mcp/*.rb` — MCP client, bridge, transports, error families (collapsed). `MCP::PROTOCOL_VERSION` lives in `mcp.rb`.
+- `lib/groq_ruby/mcp/*.rb` — MCP client, bridge, transports, protocol objects, error families (collapsed). `MCP::PROTOCOL_VERSION` lives in `mcp.rb` (kept for backward compat — points at the V2024_11_05 wire string).
+- `lib/groq_ruby/mcp/transports/{stdio,http_streamable}.rb` — one transport per file.
+- `lib/groq_ruby/mcp/protocol/{v2024_11_05,v2025_11_25}.rb` — versioned protocol objects under `MCP::Protocol::*`. Class names contain underscores deliberately (mirroring the wire format) and carry an inline `rubocop:disable` for `Naming/ClassAndModuleCamelCase`.
 - `sig/groq_ruby.rbs` — public-API RBS sigs. Keep in sync when adding public API.
 - `test/**/test_*.rb` — Minitest. Real network calls are forbidden — every HTTP test stubs via WebMock; every MCP test uses `test/support/fake_mcp_transport.rb`.
 - `examples/*.rb` — runnable scripts. Each starts with `require "bundler/setup"; require "groq_ruby"`.
@@ -99,5 +111,16 @@ explicit discussion:
   `Bridge` if the LLM should be able to use it through chat
   completions. Probe optional capabilities gracefully (catch
   `JsonRpcError` / `-32601`).
+- New MCP transport → add a class under
+  `lib/groq_ruby/mcp/transports/` that `include Transport` (so
+  `send_message`/`on_message`/`stop` are mandatory) + a sibling config
+  class (`<Name>ServerConfig`) at `lib/groq_ruby/mcp/`. Wire the
+  dispatch in `Client.build_transport` / `Client.default_protocol_for`.
+- New MCP protocol version → add a class under
+  `lib/groq_ruby/mcp/protocol/` (filename uses the wire format, e.g.
+  `v2025_11_25.rb` → `Protocol::V2025_11_25`) and register it in
+  `Protocol.registry`. Add a Zeitwerk inflection in `lib/groq_ruby.rb`.
+  Carry the `rubocop:disable Naming/ClassAndModuleCamelCase` inline on
+  the class.
 - New public method → add a YARD `@param`/`@return`/`@raise` and
   update `sig/groq_ruby.rbs`.

data/README.md

@@ -8,7 +8,8 @@ shape: typed response objects, single-purpose resource classes, internal
 `dry-monads` `Result` pipelines, and request validation via
 `dry-schema`. Streaming chat completions are supported via Server-Sent
 Events. A built-in [MCP](https://modelcontextprotocol.io) client lets you
-wire one or more MCP servers into a Groq chat completion as tools.
+wire one or more MCP servers — local stdio processes or remote HTTP
+endpoints — into a Groq chat completion as tools.
 
 This gem is **not** an official Groq product. The wire protocol it
 implements and the API surface it mirrors come from the publicly
@@ -240,8 +241,9 @@ client.batches.cancel(batch.id)
 
 ## MCP — Model Context Protocol
 
-`groq_ruby` ships with a stdio MCP client, so a Groq agent can use tools
-exposed by any MCP-compatible server (filesystem, web, custom tooling).
+`groq_ruby` ships with stdio and HTTP Streamable MCP clients, so a Groq
+agent can use tools exposed by any MCP-compatible server — local
+processes (filesystem, custom tooling) or remote HTTPS endpoints.
 Coverage matches what host applications like Claude Desktop surface:
 
 | MCP capability          | Coverage                                                                                                                                                                             |
@@ -257,40 +259,67 @@ empty for that server.
 
 ### Configuring servers
 
-Build `ServerConfig` directly, or load from the same JSON shape Claude
-Desktop uses (`mcpServers` block). The Claude Desktop adapter expands
-`${VAR}` references against each server's `env` block first, then the
-process's `ENV`, and raises on unresolved references.
+Two transports are available — pick by config class:
+
+- `ServerConfig` → **stdio**, child process launched locally.
+- `HttpServerConfig` → **HTTP Streamable**, single HTTPS endpoint
+  (the transport defined for MCP 2025-03-26+ and required by 2025-11-25).
 
 ```ruby
-# (a) direct
-config = GroqRuby::MCP::ServerConfig.new(
+# (a) stdio — local process
+fs = GroqRuby::MCP::ServerConfig.new(
   name: "fs",
   command: "npx",
   args: ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/docs"]
 )
 
-# (b) load Claude Desktop JSON
+# (b) HTTP — remote endpoint, headers carry auth
+remote = GroqRuby::MCP::HttpServerConfig.new(
+  name: "spectrum-ferret",
+  url: "https://mcp-staging.spectrumferret.com/mcp",
+  headers: {"Authorization" => "Bearer #{ENV.fetch("SF_TOKEN")}"}
+)
+
+bridge = GroqRuby::MCP::Bridge.new([fs, remote])  # mix freely
+```
+
+Or load the same JSON shape Claude Desktop uses (`mcpServers` block) for
+stdio servers — the adapter expands `${VAR}` references against each
+server's `env` block first, then the process's `ENV`, and raises on
+unresolved references.
+
+```ruby
 configs = GroqRuby::MCP::ClaudeDesktopConfig.load(
   "~/Library/Application Support/Claude/claude_desktop_config.json"
 )
 bridge = GroqRuby::MCP::Bridge.new(configs)
+```
 
-# (c) parse an in-memory hash (e.g. for a private server with a PAT)
-configs = GroqRuby::MCP::ClaudeDesktopConfig.parse({
-  "mcpServers" => {
-    "spectrum-ferret-staging" => {
-      "command" => "npx",
-      "args" => [
-        "-y", "mcp-remote@latest", "https://mcp-staging.spectrumferret.com",
-        "--header", "Authorization: Bearer ${SF_PAT}"
-      ],
-      "env" => {"SF_PAT" => ENV.fetch("SF_PAT")}
-    }
-  }
-})
+#### Picking a protocol version
+
+Each `Client` carries a `Protocol` object that selects an MCP spec year.
+Defaults are sensible for each transport:
+
+| Transport          | Default protocol  |
+|--------------------|-------------------|
+| `ServerConfig`     | `Protocol::V2024_11_05` |
+| `HttpServerConfig` | `Protocol::V2025_11_25` |
+
+Override per-client when you need to:
+
+```ruby
+mcp = GroqRuby::MCP::Client.connect(
+  config,
+  protocol: GroqRuby::MCP::Protocol::V2024_11_05.new
+)
+
+mcp.protocol.version  # => "2024-11-05"
 ```
 
+`GroqRuby::MCP::Protocol.for("2025-11-25")` returns the matching class
+(or `nil` for unknown versions); `Protocol.default` returns the
+conservative default (`V2024_11_05`).
+
 ### Direct usage
 
 ```ruby
@@ -321,7 +350,7 @@ mcp.stop
 
 `Bridge` does three things at construction:
 
-1. spawns each `ServerConfig`'s child process via stdio,
+1. opens a transport for each config (stdio child process for `ServerConfig`, HTTPS connection for `HttpServerConfig`),
 2. runs the MCP `initialize` handshake and asks each server for its tool list,
 3. indexes those tools by namespaced name `<server>__<tool>` so collisions across servers are impossible.
 
@@ -443,7 +472,7 @@ Hierarchy:
 | `GroqRuby::InternalServerError`      | 5xx                                                    |
 | `GroqRuby::APIResponseError`         | API returned an unexpected payload                     |
 | `GroqRuby::MCP::Error`               | Base for any MCP-layer failure                         |
-| `GroqRuby::MCP::TransportError`      | Stdio pipe broke or process exited                     |
+| `GroqRuby::MCP::TransportError`      | Stdio pipe broke / HTTP request failed / non-2xx       |
 | `GroqRuby::MCP::TimeoutError`        | MCP request timed out                                  |
 | `GroqRuby::MCP::ProtocolError`       | Server sent malformed JSON-RPC                         |
 | `GroqRuby::MCP::JsonRpcError`        | Server returned a JSON-RPC `error`                     |
@@ -469,6 +498,9 @@ The python SDK has a few features that aren't in `groq_ruby` v1:
 - `with_raw_response` / `with_streaming_response` accessors (responses are always parsed into typed models).
 - Built-in retries / backoff (handle in your own caller).
 - MCP sampling and `notifications/list_changed` (resource and prompt inventories are snapshotted at `Bridge` construction).
+- MCP tasks API (`tasks/get`, `tasks/result`, `tasks/list`, `tasks/cancel`) and `notifications/tasks/status` from the 2025-11-25 spec — the transport is in place; the methods land in a follow-up.
+- Long-lived `GET` SSE channel for server-initiated notifications without an in-flight request — request-correlated SSE responses on `POST` are supported.
+- MCP version negotiation downgrade: the `Protocol` object selected at construction is the version sent on every request; the server's response `protocolVersion` is recorded in `server_capabilities` but isn't auto-applied.
 
 ## Development
 

data/examples/README.md

@@ -19,6 +19,7 @@ bundle exec examples/error_handling.rb
 bundle exec examples/mcp_agent.rb /path/to/sandbox             # needs npx
 bundle exec examples/mcp_chat_with_tools.rb /path/to/sandbox   # needs npx
 bundle exec examples/mcp_resources_and_prompts.rb /path/to/sandbox  # needs npx
+SF_TOKEN=... bundle exec examples/mcp_http_remote.rb           # remote HTTP MCP server
 ```
 
 | Script                         | Endpoint                                     | What it shows                                    |
@@ -37,3 +38,4 @@ bundle exec examples/mcp_resources_and_prompts.rb /path/to/sandbox  # needs npx
 | `mcp_agent.rb`                 | chat.completions + MCP                       | Minimal agent loop — bridge tools, dispatch tool_calls back |
 | `mcp_chat_with_tools.rb`       | chat.completions + MCP                       | Heavily annotated walkthrough of the same loop, step by step |
 | `mcp_resources_and_prompts.rb` | chat.completions + MCP                       | Full coverage: tools + resources (synthetic read_resource) + prompts |
+| `mcp_http_remote.rb`           | MCP over HTTP Streamable transport           | Connect to a remote MCP server (no child process), list its tools |

data/examples/mcp_http_remote.rb

@@ -0,0 +1,47 @@
+#!/usr/bin/env ruby
+# Talk to a remote MCP server over HTTP Streamable transport (no stdio,
+# no child process, no `npx`). The server is reached at a single HTTPS
+# endpoint and may speak the 2025-11-25 MCP protocol.
+#
+# Usage:
+#   GROQ_API_KEY=gsk_... \
+#   SF_TOKEN=...         \
+#   bundle exec examples/mcp_http_remote.rb
+#
+# By default this connects to the Spectrum Ferret staging MCP server.
+# Override with MCP_URL=https://your-server/mcp.
+
+require "bundler/setup"
+require "groq_ruby"
+require "json"
+
+url = ENV.fetch("MCP_URL", "https://mcp-staging.spectrumferret.com/mcp")
+token = ENV["SF_TOKEN"]
+
+headers = {}
+headers["Authorization"] = "Bearer #{token}" if token
+
+config = GroqRuby::MCP::HttpServerConfig.new(
+  name: "remote",
+  url: url,
+  headers: headers
+)
+
+# By default Client.connect picks Protocol::V2025_11_25 for HTTP configs.
+# Pass protocol: explicitly if you want to pin a specific version, e.g.
+#   GroqRuby::MCP::Client.connect(config, protocol: GroqRuby::MCP::Protocol::V2024_11_05.new)
+mcp = GroqRuby::MCP::Client.connect(config)
+
+begin
+  puts "Connected to: #{mcp.server_name} #{mcp.server_version}"
+  puts "Protocol:     #{mcp.protocol.version}"
+  puts "Capabilities: #{mcp.server_capabilities.keys.join(", ")}"
+  puts
+
+  tools = mcp.tools_list
+  puts "Tools (#{tools.size}):"
+  tools.first(10).each { |t| puts "  - #{t.name}: #{t.description}" }
+  puts "  ..." if tools.size > 10
+ensure
+  mcp.stop
+end

data/lib/groq_ruby/mcp/client.rb

@@ -18,15 +18,39 @@ module GroqRuby
     class Client
       DEFAULT_REQUEST_TIMEOUT = 30.0
 
-      # Connect to a server via the default stdio transport and complete
-      # the initialize handshake. Caller must call {#stop} when done.
+      # Connect to a server and complete the initialize handshake. The
+      # transport is chosen by config type — {ServerConfig} → stdio,
+      # {HttpServerConfig} → HTTP Streamable. Caller must call {#stop}
+      # when done.
       #
-      # @param config [ServerConfig]
+      # @param config [ServerConfig, HttpServerConfig]
       # @param request_timeout [Numeric] seconds to wait for any single response
+      # @param protocol [Object, nil] protocol object selecting an MCP spec
+      #   year. If `nil`, a sensible default is picked from the config type
+      #   (stdio → 2024-11-05, HTTP → 2025-11-25).
       # @return [Client]
-      def self.connect(config, request_timeout: DEFAULT_REQUEST_TIMEOUT)
-        transport = Transports::Stdio.spawn(config)
-        new(transport, request_timeout: request_timeout).tap(&:initialize_session)
+      def self.connect(config, request_timeout: DEFAULT_REQUEST_TIMEOUT, protocol: nil)
+        protocol ||= default_protocol_for(config)
+        transport = build_transport(config, protocol)
+        new(transport, request_timeout: request_timeout, protocol: protocol).tap(&:initialize_session)
+      end
+
+      # @api private
+      def self.build_transport(config, protocol)
+        case config
+        when HttpServerConfig
+          Transports::HttpStreamable.start(config, protocol_version: protocol.version)
+        else
+          Transports::Stdio.spawn(config)
+        end
+      end
+
+      # @api private
+      def self.default_protocol_for(config)
+        case config
+        when HttpServerConfig then Protocol::V2025_11_25.new
+        else Protocol::V2024_11_05.new
+        end
       end
 
       # @return [String, nil] the server-reported name, populated after handshake
@@ -35,12 +59,16 @@ module GroqRuby
       attr_reader :server_version
       # @return [Hash] the server's advertised capabilities
       attr_reader :server_capabilities
+      # @return [Object] the protocol object in use
+      attr_reader :protocol
 
       # @param transport [Transport]
       # @param request_timeout [Numeric]
-      def initialize(transport, request_timeout: DEFAULT_REQUEST_TIMEOUT)
+      # @param protocol [Object] protocol object selecting an MCP spec year
+      def initialize(transport, request_timeout: DEFAULT_REQUEST_TIMEOUT, protocol: Protocol.default)
         @transport = transport
         @request_timeout = request_timeout
+        @protocol = protocol
         @next_id = 0
         @id_mutex = Mutex.new
         @pending = {}
@@ -52,11 +80,9 @@ module GroqRuby
       # {.connect}; safe to call again to re-handshake.
       # @return [Hash] the server's response payload
       def initialize_session
-        result = request("initialize", {
-          protocolVersion: PROTOCOL_VERSION,
-          capabilities: {},
-          clientInfo: {name: "groq_ruby", version: GroqRuby::VERSION}
-        })
+        result = request("initialize", @protocol.initialize_params(
+          client_info: {name: "groq_ruby", version: GroqRuby::VERSION}
+        ))
         info = result["serverInfo"] || {}
         @server_name = info["name"]
         @server_version = info["version"]

data/lib/groq_ruby/mcp/http_server_config.rb

@@ -0,0 +1,25 @@
+module GroqRuby
+  module MCP
+    # Description of an MCP server reachable over HTTP Streamable transport.
+    # Sibling of {ServerConfig} (which describes a stdio-launched server).
+    # Immutable — build one per server, then pass to {Client.connect} or
+    # {Bridge.new}.
+    #
+    # @example A remote MCP server with bearer auth
+    #   HttpServerConfig.new(
+    #     name: "spectrumferret",
+    #     url: "https://mcp-staging.spectrumferret.com/mcp",
+    #     headers: {"Authorization" => "Bearer #{ENV['SF_TOKEN']}"}
+    #   )
+    class HttpServerConfig < Data.define(:name, :url, :headers)
+      # @param name [String] short identifier used to namespace tools in {Bridge}
+      # @param url [String] full URL of the MCP endpoint (single endpoint —
+      #   the transport POSTs JSON-RPC and may receive SSE responses)
+      # @param headers [Hash{String => String}] extra HTTP headers added to
+      #   every request (e.g. authorization)
+      def initialize(name:, url:, headers: {})
+        super
+      end
+    end
+  end
+end

data/lib/groq_ruby/mcp/protocol/v2024_11_05.rb

@@ -0,0 +1,29 @@
+module GroqRuby
+  module MCP
+    module Protocol
+      # MCP protocol version 2024-11-05 — the original public release.
+      # Stdio transport only; no tasks, no elicitation, no _meta fields.
+      #
+      # Class name underscores deliberately mirror the wire format.
+      class V2024_11_05 # rubocop:disable Naming/ClassAndModuleCamelCase
+        VERSION = "2024-11-05".freeze
+
+        # @return [String] the protocol version this object speaks
+        def version
+          VERSION
+        end
+
+        # Build the `params` payload for the JSON-RPC `initialize` request.
+        # @param client_info [Hash] `{name:, version:}` describing the client
+        # @return [Hash]
+        def initialize_params(client_info:)
+          {
+            protocolVersion: VERSION,
+            capabilities: {},
+            clientInfo: client_info
+          }
+        end
+      end
+    end
+  end
+end

data/lib/groq_ruby/mcp/protocol/v2025_11_25.rb

@@ -0,0 +1,33 @@
+module GroqRuby
+  module MCP
+    module Protocol
+      # MCP protocol version 2025-11-25 — "The Task Master".
+      # HTTP/HTTPS transport only (no stdio). Adds tasks API, structured
+      # output, _meta fields, elicitation, OAuth 2.1 — the tasks methods
+      # land in a follow-up; this stub exposes only what the HTTP transport
+      # needs (the version string for the `MCP-Protocol-Version` header
+      # and the `protocolVersion` field in `initialize`).
+      #
+      # Class name underscores deliberately mirror the wire format.
+      class V2025_11_25 # rubocop:disable Naming/ClassAndModuleCamelCase
+        VERSION = "2025-11-25".freeze
+
+        # @return [String] the protocol version this object speaks
+        def version
+          VERSION
+        end
+
+        # Build the `params` payload for the JSON-RPC `initialize` request.
+        # @param client_info [Hash] `{name:, version:}` describing the client
+        # @return [Hash]
+        def initialize_params(client_info:)
+          {
+            protocolVersion: VERSION,
+            capabilities: {},
+            clientInfo: client_info
+          }
+        end
+      end
+    end
+  end
+end

data/lib/groq_ruby/mcp/protocol.rb

@@ -0,0 +1,37 @@
+module GroqRuby
+  module MCP
+    # Per-version MCP protocol objects. A {Client} delegates version-specific
+    # decisions (initialize payload shape, supported capabilities) to one of
+    # these so callers can target different MCP spec years against the same
+    # transport.
+    #
+    #     client = GroqRuby::MCP::Client.connect(
+    #       config,
+    #       protocol: GroqRuby::MCP::Protocol::V2024_11_05.new
+    #     )
+    #
+    # Without an explicit `protocol:`, {Client} uses {.default}.
+    module Protocol
+      # Look up a protocol class by its wire version string. Returns `nil`
+      # if the version is unknown to this client.
+      # @param version [String] e.g. `"2024-11-05"`
+      # @return [Class, nil]
+      def self.for(version)
+        registry[version]
+      end
+
+      # @return [Object] a fresh instance of the default protocol
+      def self.default
+        V2024_11_05.new
+      end
+
+      # @return [Hash{String => Class}]
+      def self.registry
+        {
+          V2024_11_05::VERSION => V2024_11_05,
+          V2025_11_25::VERSION => V2025_11_25
+        }
+      end
+    end
+  end
+end

data/lib/groq_ruby/mcp/transports/http_streamable.rb

@@ -0,0 +1,221 @@
+require "net/http"
+require "uri"
+require "json"
+
+module GroqRuby
+  module MCP
+    module Transports
+      # HTTP Streamable transport (the post-stdio transport defined by the
+      # MCP spec from 2025-03-26 onward and required by 2025-11-25).
+      #
+      # Single endpoint URL. Each outbound JSON-RPC frame is a `POST` whose
+      # response is either `application/json` (one frame) or
+      # `text/event-stream` (one or more frames followed by stream close).
+      # Notifications/responses get back a 202 with no body.
+      #
+      # `Mcp-Session-Id` is captured from the response to `initialize` and
+      # echoed on every subsequent request. `MCP-Protocol-Version` goes on
+      # every request.
+      #
+      # @example
+      #   config = HttpServerConfig.new(name: "x", url: "https://example/mcp")
+      #   transport = Transports::HttpStreamable.start(config, protocol_version: "2025-11-25")
+      #   transport.on_message { |msg| ... }
+      #   transport.send_message({jsonrpc: "2.0", id: 1, method: "tools/list"})
+      #
+      # PR 2 limitation: there is no long-lived `GET` SSE channel for
+      # server-initiated notifications. Server-initiated traffic that
+      # arrives interleaved on a `POST` SSE response is dispatched, but
+      # standalone notifications (e.g. `notifications/tools/list_changed`
+      # with no in-flight request) are not yet received. Adding the GET
+      # stream is part of the tasks-API follow-up.
+      class HttpStreamable
+        include Transport
+
+        DEFAULT_OPEN_TIMEOUT = 10
+        DEFAULT_READ_TIMEOUT = 60
+
+        # Construct and return a transport ready to {#send_message}. The
+        # underlying HTTP connection is not opened until the first send;
+        # this is a pure constructor by another name.
+        # @param config [HttpServerConfig]
+        # @param protocol_version [String] e.g. `"2025-11-25"`
+        # @return [HttpStreamable]
+        def self.start(config, protocol_version:)
+          new(config, protocol_version: protocol_version)
+        end
+
+        # @return [String] protocol version sent in the `MCP-Protocol-Version`
+        #   header. Mutable so {Client} can update it after negotiation.
+        attr_accessor :protocol_version
+
+        # @return [String, nil] session id captured from the initialize
+        #   response, or `nil` if the server is stateless
+        attr_reader :session_id
+
+        # @param config [HttpServerConfig]
+        # @param protocol_version [String]
+        # @param open_timeout [Numeric]
+        # @param read_timeout [Numeric]
+        def initialize(config, protocol_version:, open_timeout: DEFAULT_OPEN_TIMEOUT, read_timeout: DEFAULT_READ_TIMEOUT)
+          @config = config
+          @protocol_version = protocol_version
+          @open_timeout = open_timeout
+          @read_timeout = read_timeout
+          @uri = URI.parse(config.url)
+          @on_message = nil
+          @session_id = nil
+          @session_mutex = Mutex.new
+          @threads = []
+          @threads_mutex = Mutex.new
+          @stopped = false
+        end
+
+        def send_message(message)
+          return if @stopped
+          thread = Thread.new { post(message) }
+          @threads_mutex.synchronize { @threads << thread }
+          nil
+        end
+
+        def on_message(&block)
+          @on_message = block
+        end
+
+        def stop
+          return if @stopped
+          @stopped = true
+          drain_threads
+          delete_session if @session_id
+        end
+
+        private
+
+        # Wait for in-flight POSTs to finish so we don't leave straggler
+        # threads making HTTP requests after the caller thinks we've shut
+        # down (especially important in tests, where stale threads pollute
+        # the next test's expectations).
+        def drain_threads
+          threads = @threads_mutex.synchronize { @threads.dup }
+          threads.each { |t| t.join(@read_timeout) }
+        end
+
+        def post(message)
+          req = build_request(Net::HTTP::Post, body: JSON.generate(message))
+          with_http do |http|
+            http.request(req) do |resp|
+              capture_session_id(resp)
+              handle_response(resp, message)
+            end
+          end
+        rescue => e
+          surface_request_failure(message, e)
+        end
+
+        def delete_session
+          req = build_request(Net::HTTP::Delete)
+          with_http { |http| http.request(req) }
+        rescue
+          # Session termination is best-effort; the server will GC stale
+          # sessions on its own.
+        end
+
+        def with_http(&block)
+          http = Net::HTTP.new(@uri.host, @uri.port)
+          http.use_ssl = (@uri.scheme == "https")
+          http.open_timeout = @open_timeout
+          http.read_timeout = @read_timeout
+          http.start(&block)
+        end
+
+        def build_request(klass, body: nil)
+          req = klass.new(@uri.request_uri)
+          apply_headers(req)
+          if body
+            req.body = body
+            req["Content-Type"] = "application/json"
+          end
+          req
+        end
+
+        def apply_headers(req)
+          req["Accept"] = "application/json, text/event-stream"
+          req["MCP-Protocol-Version"] = @protocol_version
+          if (sid = current_session_id)
+            req["Mcp-Session-Id"] = sid
+          end
+          @config.headers.each { |k, v| req[k] = v }
+        end
+
+        def current_session_id
+          @session_mutex.synchronize { @session_id }
+        end
+
+        def capture_session_id(resp)
+          value = resp["Mcp-Session-Id"] || resp["mcp-session-id"]
+          return if value.nil? || value.empty?
+          @session_mutex.synchronize { @session_id = value }
+        end
+
+        def handle_response(resp, request_message)
+          status = resp.code.to_i
+          case status
+          when 200 then dispatch_body(resp)
+          when 202 then nil
+          else surface_request_failure(request_message, TransportError.new("HTTP #{status} from MCP server #{@config.name.inspect}"))
+          end
+        end
+
+        def dispatch_body(resp)
+          ctype = resp["Content-Type"].to_s
+          if ctype.include?("text/event-stream")
+            dispatch_sse(resp)
+          else
+            dispatch_json_body(resp)
+          end
+        end
+
+        def dispatch_json_body(resp)
+          body = read_body(resp)
+          return if body.nil? || body.empty?
+          message = JSON.parse(body)
+          @on_message&.call(message)
+        rescue JSON::ParserError
+          # Malformed; nothing actionable. Drop.
+        end
+
+        def dispatch_sse(resp)
+          parser = Streaming::EventParser.new
+          buffer = +""
+          resp.read_body { |chunk| buffer << chunk }
+          parser.feed(buffer) do |_event, data, _id, _retry|
+            next if data.nil? || data.empty?
+            begin
+              @on_message&.call(JSON.parse(data))
+            rescue JSON::ParserError
+              # Skip malformed event payloads.
+            end
+          end
+        end
+
+        def read_body(resp)
+          # Net::HTTP block form requires read_body; outside the block the
+          # body would be auto-loaded.
+          chunks = +""
+          resp.read_body { |c| chunks << c }
+          chunks
+        end
+
+        def surface_request_failure(request_message, error)
+          id = request_message[:id] || request_message["id"]
+          return unless id && @on_message
+          @on_message.call({
+            "jsonrpc" => "2.0",
+            "id" => id,
+            "error" => {"code" => -32000, "message" => error.message}
+          })
+        end
+      end
+    end
+  end
+end

data/lib/groq_ruby/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module GroqRuby
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/groq_ruby.rb

@@ -9,7 +9,9 @@ loader.inflector.inflect(
   "api_connection_error" => "APIConnectionError",
   "api_timeout_error" => "APITimeoutError",
   "api_status_error" => "APIStatusError",
-  "api_response_error" => "APIResponseError"
+  "api_response_error" => "APIResponseError",
+  "v2024_11_05" => "V2024_11_05",
+  "v2025_11_25" => "V2025_11_25"
 )
 # Collapse organizational sub-directories so files inside them define
 # constants in the parent namespace. Public API stays flat — callers

data/sig/groq_ruby.rbs

@@ -124,6 +124,18 @@ module GroqRuby
       ) -> void
     end
 
+    class HttpServerConfig
+      attr_reader name: String
+      attr_reader url: String
+      attr_reader headers: Hash[String, String]
+
+      def initialize: (
+        name: String,
+        url: String,
+        ?headers: Hash[String, String]
+      ) -> void
+    end
+
     module ClaudeDesktopConfig
       VAR_PATTERN: Regexp
 
@@ -131,6 +143,24 @@ module GroqRuby
       def self.parse: ((Hash[untyped, untyped] | String) input) -> Array[ServerConfig]
     end
 
+    module Protocol
+      def self.for: (String version) -> untyped
+      def self.default: () -> untyped
+      def self.registry: () -> Hash[String, untyped]
+
+      class V2024_11_05
+        VERSION: String
+        def version: () -> String
+        def initialize_params: (client_info: Hash[Symbol, String]) -> Hash[Symbol, untyped]
+      end
+
+      class V2025_11_25
+        VERSION: String
+        def version: () -> String
+        def initialize_params: (client_info: Hash[Symbol, String]) -> Hash[Symbol, untyped]
+      end
+    end
+
     class Tool
       attr_reader name: String
       attr_reader description: String?
@@ -159,9 +189,10 @@ module GroqRuby
       attr_reader server_name: String?
       attr_reader server_version: String?
       attr_reader server_capabilities: Hash[String, untyped]
+      attr_reader protocol: untyped
 
-      def self.connect: (ServerConfig, ?request_timeout: Numeric) -> Client
-      def initialize: (untyped transport, ?request_timeout: Numeric) -> void
+      def self.connect: ((ServerConfig | HttpServerConfig) config, ?request_timeout: Numeric, ?protocol: untyped) -> Client
+      def initialize: (untyped transport, ?request_timeout: Numeric, ?protocol: untyped) -> void
       def initialize_session: () -> Hash[String, untyped]
       def tools_list: () -> Array[Tool]
       def tools_call: (name: String, ?arguments: Hash[untyped, untyped]) -> Hash[String, untyped]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: groq_ruby
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Pawel Osiczko
@@ -118,6 +118,7 @@ files:
 - examples/file_upload.rb
 - examples/mcp_agent.rb
 - examples/mcp_chat_with_tools.rb
+- examples/mcp_http_remote.rb
 - examples/mcp_resources_and_prompts.rb
 - examples/models_list.rb
 - examples/speech.rb
@@ -153,12 +154,17 @@ files:
 - lib/groq_ruby/mcp/errors/timeout_error.rb
 - lib/groq_ruby/mcp/errors/transport_error.rb
 - lib/groq_ruby/mcp/errors/unknown_tool_error.rb
+- lib/groq_ruby/mcp/http_server_config.rb
 - lib/groq_ruby/mcp/json_rpc.rb
 - lib/groq_ruby/mcp/prompt.rb
+- lib/groq_ruby/mcp/protocol.rb
+- lib/groq_ruby/mcp/protocol/v2024_11_05.rb
+- lib/groq_ruby/mcp/protocol/v2025_11_25.rb
 - lib/groq_ruby/mcp/resource.rb
 - lib/groq_ruby/mcp/server_config.rb
 - lib/groq_ruby/mcp/tool.rb
 - lib/groq_ruby/mcp/transport.rb
+- lib/groq_ruby/mcp/transports/http_streamable.rb
 - lib/groq_ruby/mcp/transports/stdio.rb
 - lib/groq_ruby/models/audio/transcription.rb
 - lib/groq_ruby/models/audio/translation.rb