mcp 0.18.0 → 0.20.0

data/lib/mcp/client/oauth/provider.rb

@@ -3,9 +3,11 @@
 module MCP
   class Client
     module OAuth
-      # Pluggable OAuth client configuration handed to `MCP::Client::HTTP` via
-      # the `oauth:` keyword. Inspired by the OAuthClientProvider in the TypeScript SDK
-      # and httpx.Auth-based provider in the Python SDK.
+      # Pluggable OAuth client configuration for the OAuth 2.1 Authorization Code + PKCE flow,
+      # handed to `MCP::Client::HTTP` via the `oauth:` keyword.
+      # Inspired by the OAuthClientProvider in the TypeScript SDK and the httpx.Auth-based provider
+      # in the Python SDK. For the non-interactive machine-to-machine `client_credentials` grant,
+      # use `ClientCredentialsProvider` instead.
       #
       # Required keyword arguments:
       # - `client_metadata`  - Hash sent to the authorization server's Dynamic Client
@@ -25,7 +27,19 @@ module MCP
       # - `storage` - Object responding to `tokens`, `save_tokens(tokens)`,
       #   `client_information`, and `save_client_information(info)`. Defaults to
       #   an `InMemoryStorage`.
+      # - `client_id_metadata_document_url` - URL where the client publishes its Client ID Metadata Document
+      #   (`draft-ietf-oauth-client-id-metadata-document-00` and the MCP authorization specification).
+      #   When the authorization server advertises `client_id_metadata_document_supported: true`,
+      #   the SDK uses this URL as the OAuth `client_id` and skips Dynamic Client Registration.
+      #   Spec-required: `https://` scheme, a non-root path, and no fragment, userinfo, or `.`/`..` segments.
+      #   The SDK additionally refuses to send query strings (the draft marks them only SHOULD NOT include,
+      #   but different encodings of the same query would yield different `client_id` strings for the same document).
+      #   The document served at the URL is a separate JSON artifact from the `client_metadata` keyword:
+      #   DCR `client_metadata` MUST NOT include `client_id`, while the CIMD document MUST include `client_id` set
+      #   to the URL, `client_name`, and `redirect_uris` covering `redirect_uri`.
       class Provider
+        include StorageBackedProvider
+
         # Raised when `Provider#initialize` is called with a `redirect_uri` that
         # is neither HTTPS nor a loopback `http://` URL, per the MCP
         # authorization spec's Communication Security requirement.
@@ -38,12 +52,21 @@ module MCP
         # runtime; failing at construction surfaces the bug earlier.
         class UnregisteredRedirectURIError < ArgumentError; end
 
+        # Raised when `client_id_metadata_document_url` is provided but does not meet
+        # the structural requirements for a Client ID Metadata Document URL:
+        # HTTPS, non-root path, and no fragment, query, userinfo, or `.`/`..` segments.
+        # The CIMD URL is sent to the authorization server as the OAuth `client_id`,
+        # so the same Communication Security guarantee that protects the redirect URI
+        # applies and the value must unambiguously identify the document.
+        class InvalidClientIDMetadataDocumentURLError < ArgumentError; end
+
         attr_reader :client_metadata,
           :redirect_uri,
           :scope,
           :storage,
           :redirect_handler,
-          :callback_handler
+          :callback_handler,
+          :client_id_metadata_document_url
 
         def initialize(
           client_metadata:,
@@ -51,7 +74,8 @@ module MCP
           redirect_handler:,
           callback_handler:,
           scope: nil,
-          storage: nil
+          storage: nil,
+          client_id_metadata_document_url: nil
         )
           unless Discovery.secure_url?(redirect_uri)
             raise InsecureRedirectURIError,
@@ -66,36 +90,27 @@ module MCP
                 "(got #{registered.inspect}); otherwise the authorization server will reject the authorization request."
           end
 
+          if client_id_metadata_document_url && !Discovery.client_id_metadata_document_url?(client_id_metadata_document_url)
+            raise InvalidClientIDMetadataDocumentURLError,
+              "client_id_metadata_document_url #{client_id_metadata_document_url.inspect} must be an https URL " \
+                "with a non-root path and no fragment, query, userinfo, or `.`/`..` segments, " \
+                "per the MCP authorization specification and `draft-ietf-oauth-client-id-metadata-document`."
+          end
+
           @client_metadata = client_metadata
           @redirect_uri = redirect_uri
           @redirect_handler = redirect_handler
           @callback_handler = callback_handler
           @scope = scope
           @storage = storage || InMemoryStorage.new
+          @client_id_metadata_document_url = client_id_metadata_document_url
         end
 
-        def access_token
-          tokens&.dig("access_token") || tokens&.dig(:access_token)
-        end
-
-        def tokens
-          @storage.tokens
-        end
-
-        def save_tokens(tokens)
-          @storage.save_tokens(tokens)
-        end
-
-        def client_information
-          @storage.client_information
-        end
-
-        def save_client_information(info)
-          @storage.save_client_information(info)
-        end
-
-        def clear_tokens!
-          @storage.save_tokens(nil)
+        # Identifies the OAuth flow this provider drives.
+        # `Flow` dispatches on this rather than inspecting `client_metadata[:grant_types]`,
+        # which is protocol metadata for the authorization server, not an SDK control signal.
+        def authorization_flow
+          :authorization_code
         end
       end
     end

data/lib/mcp/client/oauth/storage_backed_provider.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module MCP
+  class Client
+    module OAuth
+      # Shared token/credential persistence for the OAuth provider classes
+      # (`Provider` for the authorization-code flow and `ClientCredentialsProvider`
+      # for the client_credentials flow). The two grants differ in how they authenticate,
+      # but both read and write the same two pieces of state through a `storage` object:
+      # the token response and the client information. This module supplies that delegation
+      # so the `Flow` orchestrator can treat any provider uniformly.
+      #
+      # Including classes must set `@storage` to an object responding to `tokens`,
+      # `save_tokens(tokens)`, `client_information`, and `save_client_information(info)`
+      # (see `InMemoryStorage`).
+      module StorageBackedProvider
+        def access_token
+          tokens&.dig("access_token") || tokens&.dig(:access_token)
+        end
+
+        def tokens
+          @storage.tokens
+        end
+
+        def save_tokens(tokens)
+          @storage.save_tokens(tokens)
+        end
+
+        def client_information
+          @storage.client_information
+        end
+
+        def save_client_information(info)
+          @storage.save_client_information(info)
+        end
+
+        def clear_tokens!
+          @storage.save_tokens(nil)
+        end
+      end
+    end
+  end
+end

data/lib/mcp/client/oauth.rb

@@ -4,13 +4,15 @@ require_relative "oauth/discovery"
 require_relative "oauth/flow"
 require_relative "oauth/in_memory_storage"
 require_relative "oauth/pkce"
+require_relative "oauth/storage_backed_provider"
 require_relative "oauth/provider"
+require_relative "oauth/client_credentials_provider"
 
 module MCP
   class Client
     # OAuth client support for the MCP Authorization spec (PRM discovery,
     # Authorization Server metadata discovery, Dynamic Client Registration,
-    # OAuth 2.1 Authorization Code + PKCE).
+    # OAuth 2.1 Authorization Code + PKCE, and the client_credentials grant).
     # https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization
     module OAuth
     end

data/lib/mcp/client.rb

@@ -103,6 +103,8 @@ module MCP
     # Returns a single page of tools from the server.
     #
     # @param cursor [String, nil] Cursor from a previous page response.
+    # @param meta [Hash, nil] Additional `_meta` entries to send with the request,
+    #   e.g. SEP-414 trace context (see {MCP::TraceContext}).
     # @return [MCP::Client::ListToolsResult] Result with `tools` (Array<MCP::Client::Tool>)
     #   and `next_cursor` (String or nil).
     #
@@ -114,9 +116,9 @@ module MCP
     #     cursor = page.next_cursor
     #     break unless cursor
     #   end
-    def list_tools(cursor: nil)
+    def list_tools(cursor: nil, meta: nil)
       params = cursor ? { cursor: cursor } : nil
-      response = request(method: "tools/list", params: params)
+      response = request(method: "tools/list", params: params, meta: meta)
       result = response["result"] || {}
 
       tools = (result["tools"] || []).map do |tool|
@@ -146,31 +148,19 @@ module MCP
     #   end
     def tools
       # TODO: consider renaming to `list_all_tools`.
-      all_tools = []
-      seen = Set.new
-      cursor = nil
-
-      loop do
-        page = list_tools(cursor: cursor)
-        all_tools.concat(page.tools)
-        next_cursor = page.next_cursor
-        break if next_cursor.nil? || seen.include?(next_cursor)
-
-        seen << next_cursor
-        cursor = next_cursor
-      end
-
-      all_tools
+      fetch_all_pages { |cursor| list_tools(cursor: cursor) }.flat_map(&:tools)
     end
 
     # Returns a single page of resources from the server.
     #
     # @param cursor [String, nil] Cursor from a previous page response.
+    # @param meta [Hash, nil] Additional `_meta` entries to send with the request,
+    #   e.g. SEP-414 trace context (see {MCP::TraceContext}).
     # @return [MCP::Client::ListResourcesResult] Result with `resources` (Array<Hash>)
     #   and `next_cursor` (String or nil).
-    def list_resources(cursor: nil)
+    def list_resources(cursor: nil, meta: nil)
       params = cursor ? { cursor: cursor } : nil
-      response = request(method: "resources/list", params: params)
+      response = request(method: "resources/list", params: params, meta: meta)
       result = response["result"] || {}
 
       ListResourcesResult.new(
@@ -189,31 +179,19 @@ module MCP
     # @return [Array<Hash>] An array of available resources.
     def resources
       # TODO: consider renaming to `list_all_resources`.
-      all_resources = []
-      seen = Set.new
-      cursor = nil
-
-      loop do
-        page = list_resources(cursor: cursor)
-        all_resources.concat(page.resources)
-        next_cursor = page.next_cursor
-        break if next_cursor.nil? || seen.include?(next_cursor)
-
-        seen << next_cursor
-        cursor = next_cursor
-      end
-
-      all_resources
+      fetch_all_pages { |cursor| list_resources(cursor: cursor) }.flat_map(&:resources)
     end
 
     # Returns a single page of resource templates from the server.
     #
     # @param cursor [String, nil] Cursor from a previous page response.
+    # @param meta [Hash, nil] Additional `_meta` entries to send with the request,
+    #   e.g. SEP-414 trace context (see {MCP::TraceContext}).
     # @return [MCP::Client::ListResourceTemplatesResult] Result with `resource_templates`
     #   (Array<Hash>) and `next_cursor` (String or nil).
-    def list_resource_templates(cursor: nil)
+    def list_resource_templates(cursor: nil, meta: nil)
       params = cursor ? { cursor: cursor } : nil
-      response = request(method: "resources/templates/list", params: params)
+      response = request(method: "resources/templates/list", params: params, meta: meta)
       result = response["result"] || {}
 
       ListResourceTemplatesResult.new(
@@ -232,31 +210,19 @@ module MCP
     # @return [Array<Hash>] An array of available resource templates.
     def resource_templates
       # TODO: consider renaming to `list_all_resource_templates`.
-      all_templates = []
-      seen = Set.new
-      cursor = nil
-
-      loop do
-        page = list_resource_templates(cursor: cursor)
-        all_templates.concat(page.resource_templates)
-        next_cursor = page.next_cursor
-        break if next_cursor.nil? || seen.include?(next_cursor)
-
-        seen << next_cursor
-        cursor = next_cursor
-      end
-
-      all_templates
+      fetch_all_pages { |cursor| list_resource_templates(cursor: cursor) }.flat_map(&:resource_templates)
     end
 
     # Returns a single page of prompts from the server.
     #
     # @param cursor [String, nil] Cursor from a previous page response.
+    # @param meta [Hash, nil] Additional `_meta` entries to send with the request,
+    #   e.g. SEP-414 trace context (see {MCP::TraceContext}).
     # @return [MCP::Client::ListPromptsResult] Result with `prompts` (Array<Hash>)
     #   and `next_cursor` (String or nil).
-    def list_prompts(cursor: nil)
+    def list_prompts(cursor: nil, meta: nil)
       params = cursor ? { cursor: cursor } : nil
-      response = request(method: "prompts/list", params: params)
+      response = request(method: "prompts/list", params: params, meta: meta)
       result = response["result"] || {}
 
       ListPromptsResult.new(
@@ -275,21 +241,7 @@ module MCP
     # @return [Array<Hash>] An array of available prompts.
     def prompts
       # TODO: consider renaming to `list_all_prompts`.
-      all_prompts = []
-      seen = Set.new
-      cursor = nil
-
-      loop do
-        page = list_prompts(cursor: cursor)
-        all_prompts.concat(page.prompts)
-        next_cursor = page.next_cursor
-        break if next_cursor.nil? || seen.include?(next_cursor)
-
-        seen << next_cursor
-        cursor = next_cursor
-      end
-
-      all_prompts
+      fetch_all_pages { |cursor| list_prompts(cursor: cursor) }.flat_map(&:prompts)
     end
 
     # Calls a tool via the transport layer and returns the full response from the server.
@@ -298,6 +250,10 @@ module MCP
     # @param tool [MCP::Client::Tool] The tool to be called.
     # @param arguments [Object, nil] The arguments to pass to the tool.
     # @param progress_token [String, Integer, nil] A token to request progress notifications from the server during tool execution.
+    # @param meta [Hash, nil] Additional `_meta` entries to send with the request,
+    #   e.g. the W3C Trace Context keys reserved by SEP-414
+    #   (`MCP::TraceContext::TRACEPARENT_META_KEY`, `tracestate`, `baggage`).
+    #   `progress_token` takes precedence over a `progressToken` entry in `meta`.
     # @return [Hash] The full JSON-RPC response from the transport.
     #
     # @example Call by name
@@ -312,14 +268,17 @@ module MCP
     # @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(name: nil, tool: nil, arguments: nil, progress_token: nil)
+    def call_tool(name: nil, tool: nil, arguments: nil, progress_token: nil, meta: nil)
       tool_name = name || tool&.name
       raise ArgumentError, "Either `name:` or `tool:` must be provided." unless tool_name
 
       params = { name: tool_name, arguments: arguments }
+      meta_entries = meta ? meta.dup : {}
       if progress_token
-        params[:_meta] = { progressToken: progress_token }
+        meta_entries.delete("progressToken")
+        meta_entries[:progressToken] = progress_token
       end
+      params[:_meta] = meta_entries unless meta_entries.empty?
 
       request(method: "tools/call", params: params)
     end
@@ -327,9 +286,11 @@ module MCP
     # Reads a resource from the server by URI and returns the contents.
     #
     # @param uri [String] The URI of the resource to read.
+    # @param meta [Hash, nil] Additional `_meta` entries to send with the request,
+    #   e.g. SEP-414 trace context (see {MCP::TraceContext}).
     # @return [Array<Hash>] An array of resource contents (text or blob).
-    def read_resource(uri:)
-      response = request(method: "resources/read", params: { uri: uri })
+    def read_resource(uri:, meta: nil)
+      response = request(method: "resources/read", params: { uri: uri }, meta: meta)
 
       response.dig("result", "contents") || []
     end
@@ -337,9 +298,11 @@ module MCP
     # Gets a prompt from the server by name and returns its details.
     #
     # @param name [String] The name of the prompt to get.
+    # @param meta [Hash, nil] Additional `_meta` entries to send with the request,
+    #   e.g. SEP-414 trace context (see {MCP::TraceContext}).
     # @return [Hash] A hash containing the prompt details.
-    def get_prompt(name:)
-      response = request(method: "prompts/get", params: { name: name })
+    def get_prompt(name:, meta: nil)
+      response = request(method: "prompts/get", params: { name: name }, meta: meta)
 
       response.fetch("result", {})
     end
@@ -350,12 +313,14 @@ module MCP
     #   or `{ type: "ref/resource", uri: "file:///{path}" }`.
     # @param argument [Hash] The argument being completed, e.g. `{ name: "language", value: "py" }`.
     # @param context [Hash, nil] Optional context with previously resolved arguments.
+    # @param meta [Hash, nil] Additional `_meta` entries to send with the request,
+    #   e.g. SEP-414 trace context (see {MCP::TraceContext}).
     # @return [Hash] The completion result with `"values"`, `"hasMore"`, and optionally `"total"`.
-    def complete(ref:, argument:, context: nil)
+    def complete(ref:, argument:, context: nil, meta: nil)
       params = { ref: ref, argument: argument }
       params[:context] = context if context
 
-      response = request(method: "completion/complete", params: params)
+      response = request(method: "completion/complete", params: params, meta: meta)
 
       response.dig("result", "completion") || { "values" => [], "hasMore" => false }
     end
@@ -371,8 +336,8 @@ module MCP
     #   client.ping # => {}
     #
     # @see https://modelcontextprotocol.io/specification/latest/basic/utilities/ping
-    def ping
-      result = request(method: Methods::PING)["result"]
+    def ping(meta: nil)
+      result = request(method: Methods::PING, meta: meta)["result"]
       raise ValidationError, "Response validation failed: missing or invalid `result`" unless result.is_a?(Hash)
 
       result
@@ -380,7 +345,34 @@ module MCP
 
     private
 
-    def request(method:, params: nil)
+    # Walks every page of a list endpoint, following `next_cursor`, and returns
+    # the page results. The `seen` set guards against a server that repeats or
+    # cycles cursors, so the loop always terminates.
+    def fetch_all_pages
+      pages = []
+      seen = Set.new
+      cursor = nil
+
+      loop do
+        page = yield(cursor)
+        pages << page
+        next_cursor = page.next_cursor
+        break if next_cursor.nil? || seen.include?(next_cursor)
+
+        seen << next_cursor
+        cursor = next_cursor
+      end
+
+      pages
+    end
+
+    # Merges caller-supplied `meta` entries into the request params as `_meta`,
+    # without mutating the caller's hashes. Per SEP-414, `_meta` carries
+    # request-specific metadata such as W3C trace context (`traceparent`,
+    # `tracestate`, `baggage`); see {MCP::TraceContext}.
+    def request(method:, params: nil, meta: nil)
+      params = (params || {}).merge(_meta: meta) if meta && !meta.empty?
+
       request_body = {
         jsonrpc: JsonRpcHandler::Version::V2_0,
         id: request_id,

data/lib/mcp/configuration.rb

@@ -6,6 +6,7 @@ module MCP
     SUPPORTED_STABLE_PROTOCOL_VERSIONS = [
       LATEST_STABLE_PROTOCOL_VERSION, "2025-06-18", "2025-03-26", "2024-11-05",
     ]
+    DEFAULT_NEGOTIATED_PROTOCOL_VERSION = "2025-03-26"
 
     attr_writer :exception_reporter, :around_request
 

data/lib/mcp/resource.rb

@@ -5,15 +5,17 @@ require_relative "resource/embedded"
 
 module MCP
   class Resource
-    attr_reader :uri, :name, :title, :description, :icons, :mime_type, :meta
+    attr_reader :uri, :name, :title, :description, :icons, :mime_type, :annotations, :size, :meta
 
-    def initialize(uri:, name:, title: nil, description: nil, icons: [], mime_type: nil, meta: nil)
+    def initialize(uri:, name:, title: nil, description: nil, icons: [], mime_type: nil, annotations: nil, size: nil, meta: nil)
       @uri = uri
       @name = name
       @title = title
       @description = description
       @icons = icons
       @mime_type = mime_type
+      @annotations = annotations
+      @size = size
       @meta = meta
     end
 
@@ -25,6 +27,8 @@ module MCP
         description: description,
         icons: icons&.then { |icons| icons.empty? ? nil : icons.map(&:to_h) },
         mimeType: mime_type,
+        annotations: annotations&.to_h,
+        size: size,
         _meta: meta,
       }.compact
     end

data/lib/mcp/resource_template.rb

@@ -2,15 +2,16 @@
 
 module MCP
   class ResourceTemplate
-    attr_reader :uri_template, :name, :title, :description, :icons, :mime_type, :meta
+    attr_reader :uri_template, :name, :title, :description, :icons, :mime_type, :annotations, :meta
 
-    def initialize(uri_template:, name:, title: nil, description: nil, icons: [], mime_type: nil, meta: nil)
+    def initialize(uri_template:, name:, title: nil, description: nil, icons: [], mime_type: nil, annotations: nil, meta: nil)
       @uri_template = uri_template
       @name = name
       @title = title
       @description = description
       @icons = icons
       @mime_type = mime_type
+      @annotations = annotations
       @meta = meta
     end
 
@@ -22,6 +23,7 @@ module MCP
         description: description,
         icons: icons&.then { |icons| icons.empty? ? nil : icons.map(&:to_h) },
         mimeType: mime_type,
+        annotations: annotations&.to_h,
         _meta: meta,
       }.compact
     end

data/lib/mcp/server/transports/streamable_http_transport.rb

@@ -389,7 +389,11 @@ module MCP
           end
         rescue StandardError => e
           MCP.configuration.exception_reporter.call(e, { request: body_string })
-          [500, { "Content-Type" => "application/json" }, [{ error: "Internal server error" }.to_json]]
+          json_rpc_error_response(
+            status: 500,
+            code: JsonRpcHandler::ErrorCode::INTERNAL_ERROR,
+            message: "Internal server error",
+          )
         end
 
         def handle_get(request)
@@ -513,19 +517,19 @@ module MCP
           media_type = content_type&.split(";")&.first&.strip&.downcase
           return if media_type == "application/json"
 
-          [
-            415,
-            { "Content-Type" => "application/json" },
-            [{ error: "Unsupported Media Type: Content-Type must be application/json" }.to_json],
-          ]
+          json_rpc_error_response(
+            status: 415,
+            code: JsonRpcHandler::ErrorCode::INVALID_REQUEST,
+            message: "Unsupported Media Type: Content-Type must be application/json",
+          )
         end
 
         def not_acceptable_response(required_types)
-          [
-            406,
-            { "Content-Type" => "application/json" },
-            [{ error: "Not Acceptable: Accept header must include #{required_types.join(" and ")}" }.to_json],
-          ]
+          json_rpc_error_response(
+            status: 406,
+            code: JsonRpcHandler::ErrorCode::INVALID_REQUEST,
+            message: "Not Acceptable: Accept header must include #{required_types.join(" and ")}",
+          )
         end
 
         def parse_request_body(body_string)
@@ -535,7 +539,11 @@ module MCP
         end
 
         def invalid_json_response
-          [400, { "Content-Type" => "application/json" }, [{ error: "Invalid JSON" }.to_json]]
+          json_rpc_error_response(
+            status: 400,
+            code: JsonRpcHandler::ErrorCode::PARSE_ERROR,
+            message: "Parse error: Invalid JSON",
+          )
         end
 
         def initialize_request?(body)
@@ -543,20 +551,20 @@ module MCP
         end
 
         def validate_protocol_version_header(request)
-          header_value = request.env["HTTP_MCP_PROTOCOL_VERSION"]
-          return if header_value.nil?
+          header_value = request.env["HTTP_MCP_PROTOCOL_VERSION"] || MCP::Configuration::DEFAULT_NEGOTIATED_PROTOCOL_VERSION
           return if MCP::Configuration::SUPPORTED_STABLE_PROTOCOL_VERSIONS.include?(header_value)
 
           supported = MCP::Configuration::SUPPORTED_STABLE_PROTOCOL_VERSIONS.join(", ")
-          body = {
-            jsonrpc: "2.0",
-            id: nil,
-            error: {
-              code: JsonRpcHandler::ErrorCode::INVALID_REQUEST,
-              message: "Bad Request: Unsupported protocol version: #{header_value}. Supported versions: #{supported}",
-            },
-          }
-          [400, { "Content-Type" => "application/json" }, [body.to_json]]
+          json_rpc_error_response(
+            status: 400,
+            code: JsonRpcHandler::ErrorCode::INVALID_REQUEST,
+            message: "Bad Request: Unsupported protocol version: #{header_value}. Supported versions: #{supported}",
+          )
+        end
+
+        def json_rpc_error_response(status:, code:, message:)
+          body = { jsonrpc: "2.0", id: nil, error: { code: code, message: message } }
+          [status, { "Content-Type" => "application/json" }, [body.to_json]]
         end
 
         def notification?(body)
@@ -793,15 +801,27 @@ module MCP
         end
 
         def method_not_allowed_response
-          [405, { "Content-Type" => "application/json" }, [{ error: "Method not allowed" }.to_json]]
+          json_rpc_error_response(
+            status: 405,
+            code: JsonRpcHandler::ErrorCode::INVALID_REQUEST,
+            message: "Method not allowed",
+          )
         end
 
         def missing_session_id_response
-          [400, { "Content-Type" => "application/json" }, [{ error: "Missing session ID" }.to_json]]
+          json_rpc_error_response(
+            status: 400,
+            code: JsonRpcHandler::ErrorCode::INVALID_REQUEST,
+            message: "Missing session ID",
+          )
         end
 
         def session_not_found_response
-          [404, { "Content-Type" => "application/json" }, [{ error: "Session not found" }.to_json]]
+          json_rpc_error_response(
+            status: 404,
+            code: JsonRpcHandler::ErrorCode::INVALID_REQUEST,
+            message: "Session not found",
+          )
         end
 
         def already_initialized_response(request_id)
@@ -821,11 +841,11 @@ module MCP
         end
 
         def session_already_connected_response
-          [
-            409,
-            { "Content-Type" => "application/json" },
-            [{ error: "Conflict: Only one SSE stream is allowed per session" }.to_json],
-          ]
+          json_rpc_error_response(
+            status: 409,
+            code: JsonRpcHandler::ErrorCode::INVALID_REQUEST,
+            message: "Conflict: Only one SSE stream is allowed per session",
+          )
         end
 
         def setup_sse_stream(session_id)