feat(server/mcp): support MCP version 2025-06-18 (#898)

This PR add supports to MCP version 2025-06-18 defined
[here](https://modelcontextprotocol.io/specification/2025-06-18).

The main updates includes:
* Retrieving protocol version from header via `MCP-Protocol-Version`.
* Throwing `400 Bad Request` when an invalid version is received.

internal/server/mcp.go

@@ -357,6 +357,17 @@ func httpHandler(s *Server, w http.ResponseWriter, r *http.Request) {
 		protocolVersion = v20250326.PROTOCOL_VERSION
 	}
 
+	// check if client have `MCP-Protocol-Version` header
+	headerProtocolVersion := r.Header.Get("MCP-Protocol-Version")
+	if headerProtocolVersion != "" {
+		if !mcp.VerifyProtocolVersion(headerProtocolVersion) {
+			err := fmt.Errorf("invalid protocol version: %s", headerProtocolVersion)
+			_ = render.Render(w, r, newErrResponse(err, http.StatusBadRequest))
+			return
+		}
+		protocolVersion = headerProtocolVersion
+	}
+
 	toolsetName := chi.URLParam(r, "toolsetName")
 	s.logger.DebugContext(ctx, fmt.Sprintf("toolset name: %s", toolsetName))
 	span.SetAttributes(attribute.String("toolset_name", toolsetName))
@@ -387,6 +398,7 @@ func httpHandler(s *Server, w http.ResponseWriter, r *http.Request) {
 		id := uuid.New().String()
 		s.logger.DebugContext(ctx, err.Error())
 		render.JSON(w, r, jsonrpc.NewError(id, jsonrpc.PARSE_ERROR, err.Error(), nil))
+		return
 	}
 
 	v, res, err := processMcpMessage(ctx, body, s, protocolVersion, toolsetName)
@@ -431,10 +443,6 @@ func processMcpMessage(ctx context.Context, body []byte, s *Server, protocolVers
 		return "", jsonrpc.NewError("", jsonrpc.INTERNAL_ERROR, err.Error(), nil), err
 	}
 
-	if protocolVersion == "" {
-		protocolVersion = v20241105.PROTOCOL_VERSION
-	}
-
 	// Generic baseMessage could either be a JSONRPCNotification or JSONRPCRequest
 	var baseMessage jsonrpc.BaseMessage
 	if err = util.DecodeJSON(bytes.NewBuffer(body), &baseMessage); err != nil {

internal/server/mcp/mcp.go

@@ -24,15 +24,20 @@ import (
 	mcputil "github.com/googleapis/genai-toolbox/internal/server/mcp/util"
 	v20241105 "github.com/googleapis/genai-toolbox/internal/server/mcp/v20241105"
 	v20250326 "github.com/googleapis/genai-toolbox/internal/server/mcp/v20250326"
+	v20250618 "github.com/googleapis/genai-toolbox/internal/server/mcp/v20250618"
 	"github.com/googleapis/genai-toolbox/internal/tools"
 )
 
 // LATEST_PROTOCOL_VERSION is the latest version of the MCP protocol supported.
 // Update the version used in InitializeResponse when this value is updated.
-const LATEST_PROTOCOL_VERSION = v20250326.PROTOCOL_VERSION
+const LATEST_PROTOCOL_VERSION = v20250618.PROTOCOL_VERSION
 
 // SUPPORTED_PROTOCOL_VERSIONS is the MCP protocol versions that are supported.
-var SUPPORTED_PROTOCOL_VERSIONS = []string{v20241105.PROTOCOL_VERSION, v20250326.PROTOCOL_VERSION}
+var SUPPORTED_PROTOCOL_VERSIONS = []string{
+	v20241105.PROTOCOL_VERSION,
+	v20250326.PROTOCOL_VERSION,
+	v20250618.PROTOCOL_VERSION,
+}
 
 // InitializeResponse runs capability negotiation and protocol version agreement.
 // This is the Initialization phase of the lifecycle for MCP client-server connections.
@@ -61,7 +66,9 @@ func InitializeResponse(ctx context.Context, id jsonrpc.RequestId, body []byte,
 			},
 		},
 		ServerInfo: mcputil.Implementation{
-			Name:    mcputil.SERVER_NAME,
+			BaseMetadata: mcputil.BaseMetadata{
+				Name: mcputil.SERVER_NAME,
+			},
 			Version: toolboxVersion,
 		},
 	}
@@ -88,12 +95,16 @@ func NotificationHandler(ctx context.Context, body []byte) error {
 // This is the Operation phase of the lifecycle for MCP client-server connections.
 func ProcessMethod(ctx context.Context, mcpVersion string, id jsonrpc.RequestId, method string, toolset tools.Toolset, tools map[string]tools.Tool, body []byte) (any, error) {
 	switch mcpVersion {
+	case v20250618.PROTOCOL_VERSION:
+		return v20250618.ProcessMethod(ctx, id, method, toolset, tools, body)
 	case v20250326.PROTOCOL_VERSION:
 		return v20250326.ProcessMethod(ctx, id, method, toolset, tools, body)
-	case v20241105.PROTOCOL_VERSION:
-		return v20241105.ProcessMethod(ctx, id, method, toolset, tools, body)
 	default:
-		err := fmt.Errorf("invalid protocol version: %s", mcpVersion)
-		return jsonrpc.NewError(id, jsonrpc.INVALID_REQUEST, err.Error(), nil), err
+		return v20241105.ProcessMethod(ctx, id, method, toolset, tools, body)
 	}
 }
+
+// VerifyProtocolVersion verifies if the version string is valid.
+func VerifyProtocolVersion(version string) bool {
+	return slices.Contains(SUPPORTED_PROTOCOL_VERSIONS, version)
+}

internal/server/mcp/util/lifecycle.go

@@ -89,8 +89,22 @@ type ServerCapabilities struct {
 	Tools *ListChanged `json:"tools,omitempty"`
 }
 
+// Base interface for metadata with name (identifier) and title (display name) properties.
+type BaseMetadata struct {
+	// Intended for programmatic or logical use, but used as a display name in past specs
+	// or fallback (if title isn't present).
+	Name string `json:"name"`
+	// Intended for UI and end-user contexts — optimized to be human-readable and easily understood,
+	//even by those unfamiliar with domain-specific terminology.
+	//
+	// If not provided, the name should be used for display (except for Tool,
+	// where `annotations.title` should be given precedence over using `name`,
+	// if present).
+	Title string `json:"title,omitempty"`
+}
+
 // Implementation describes the name and version of an MCP implementation.
 type Implementation struct {
-	Name    string `json:"name"`
+	BaseMetadata
 	Version string `json:"version"`
 }

internal/server/mcp/v20250618/method.go

@@ -0,0 +1,141 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package v20250618
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+
+	"github.com/googleapis/genai-toolbox/internal/server/mcp/jsonrpc"
+	"github.com/googleapis/genai-toolbox/internal/tools"
+	"github.com/googleapis/genai-toolbox/internal/util"
+)
+
+// ProcessMethod returns a response for the request.
+func ProcessMethod(ctx context.Context, id jsonrpc.RequestId, method string, toolset tools.Toolset, tools map[string]tools.Tool, body []byte) (any, error) {
+	switch method {
+	case TOOLS_LIST:
+		return toolsListHandler(id, toolset, body)
+	case TOOLS_CALL:
+		return toolsCallHandler(ctx, id, tools, body)
+	default:
+		err := fmt.Errorf("invalid method %s", method)
+		return jsonrpc.NewError(id, jsonrpc.METHOD_NOT_FOUND, err.Error(), nil), err
+	}
+}
+
+func toolsListHandler(id jsonrpc.RequestId, toolset tools.Toolset, body []byte) (any, error) {
+	var req ListToolsRequest
+	if err := json.Unmarshal(body, &req); err != nil {
+		err = fmt.Errorf("invalid mcp tools list request: %w", err)
+		return jsonrpc.NewError(id, jsonrpc.INVALID_REQUEST, err.Error(), nil), err
+	}
+
+	result := ListToolsResult{
+		Tools: toolset.McpManifest,
+	}
+	return jsonrpc.JSONRPCResponse{
+		Jsonrpc: jsonrpc.JSONRPC_VERSION,
+		Id:      id,
+		Result:  result,
+	}, nil
+}
+
+// toolsCallHandler generate a response for tools call.
+func toolsCallHandler(ctx context.Context, id jsonrpc.RequestId, tools map[string]tools.Tool, body []byte) (any, error) {
+	// retrieve logger from context
+	logger, err := util.LoggerFromContext(ctx)
+	if err != nil {
+		return jsonrpc.NewError(id, jsonrpc.INTERNAL_ERROR, err.Error(), nil), err
+	}
+
+	var req CallToolRequest
+	if err = json.Unmarshal(body, &req); err != nil {
+		err = fmt.Errorf("invalid mcp tools call request: %w", err)
+		return jsonrpc.NewError(id, jsonrpc.INVALID_REQUEST, err.Error(), nil), err
+	}
+
+	toolName := req.Params.Name
+	toolArgument := req.Params.Arguments
+	logger.DebugContext(ctx, fmt.Sprintf("tool name: %s", toolName))
+	tool, ok := tools[toolName]
+	if !ok {
+		err = fmt.Errorf("invalid tool name: tool with name %q does not exist", toolName)
+		return jsonrpc.NewError(id, jsonrpc.INVALID_PARAMS, err.Error(), nil), err
+	}
+
+	// marshal arguments and decode it using decodeJSON instead to prevent loss between floats/int.
+	aMarshal, err := json.Marshal(toolArgument)
+	if err != nil {
+		err = fmt.Errorf("unable to marshal tools argument: %w", err)
+		return jsonrpc.NewError(id, jsonrpc.INTERNAL_ERROR, err.Error(), nil), err
+	}
+
+	var data map[string]any
+	if err = util.DecodeJSON(bytes.NewBuffer(aMarshal), &data); err != nil {
+		err = fmt.Errorf("unable to decode tools argument: %w", err)
+		return jsonrpc.NewError(id, jsonrpc.INTERNAL_ERROR, err.Error(), nil), err
+	}
+
+	// claimsFromAuth maps the name of the authservice to the claims retrieved from it.
+	// Since MCP doesn't support auth, an empty map will be use every time.
+	claimsFromAuth := make(map[string]map[string]any)
+
+	params, err := tool.ParseParams(data, claimsFromAuth)
+	if err != nil {
+		err = fmt.Errorf("provided parameters were invalid: %w", err)
+		return jsonrpc.NewError(id, jsonrpc.INVALID_PARAMS, err.Error(), nil), err
+	}
+	logger.DebugContext(ctx, fmt.Sprintf("invocation params: %s", params))
+
+	if !tool.Authorized([]string{}) {
+		err = fmt.Errorf("unauthorized Tool call: `authRequired` is set for the target Tool")
+		return jsonrpc.NewError(id, jsonrpc.INVALID_REQUEST, err.Error(), nil), err
+	}
+
+	// run tool invocation and generate response.
+	results, err := tool.Invoke(ctx, params)
+	if err != nil {
+		text := TextContent{
+			Type: "text",
+			Text: err.Error(),
+		}
+		return jsonrpc.JSONRPCResponse{
+			Jsonrpc: jsonrpc.JSONRPC_VERSION,
+			Id:      id,
+			Result:  CallToolResult{Content: []TextContent{text}, IsError: true},
+		}, nil
+	}
+
+	content := make([]TextContent, 0)
+	for _, d := range results {
+		text := TextContent{Type: "text"}
+		dM, err := json.Marshal(d)
+		if err != nil {
+			text.Text = fmt.Sprintf("fail to marshal: %s, result: %s", err, d)
+		} else {
+			text.Text = string(dM)
+		}
+		content = append(content, text)
+	}
+
+	return jsonrpc.JSONRPCResponse{
+		Jsonrpc: jsonrpc.JSONRPC_VERSION,
+		Id:      id,
+		Result:  CallToolResult{Content: content},
+	}, nil
+}

internal/server/mcp/v20250618/types.go

@@ -0,0 +1,180 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package v20250618
+
+import (
+	"github.com/googleapis/genai-toolbox/internal/server/mcp/jsonrpc"
+	"github.com/googleapis/genai-toolbox/internal/tools"
+)
+
+// SERVER_NAME is the server name used in Implementation.
+const SERVER_NAME = "Toolbox"
+
+// PROTOCOL_VERSION is the version of the MCP protocol in this package.
+const PROTOCOL_VERSION = "2025-06-18"
+
+// methods that are supported.
+const (
+	TOOLS_LIST = "tools/list"
+	TOOLS_CALL = "tools/call"
+)
+
+/* Empty result */
+
+// EmptyResult represents a response that indicates success but carries no data.
+type EmptyResult jsonrpc.Result
+
+/* Pagination */
+
+// Cursor is an opaque token used to represent a cursor for pagination.
+type Cursor string
+
+type PaginatedRequest struct {
+	jsonrpc.Request
+	Params struct {
+		// An opaque token representing the current pagination position.
+		// If provided, the server should return results starting after this cursor.
+		Cursor Cursor `json:"cursor,omitempty"`
+	} `json:"params,omitempty"`
+}
+
+type PaginatedResult struct {
+	jsonrpc.Result
+	// An opaque token representing the pagination position after the last returned result.
+	// If present, there may be more results available.
+	NextCursor Cursor `json:"nextCursor,omitempty"`
+}
+
+/* Tools */
+
+// Sent from the client to request a list of tools the server has.
+type ListToolsRequest struct {
+	PaginatedRequest
+}
+
+// The server's response to a tools/list request from the client.
+type ListToolsResult struct {
+	PaginatedResult
+	Tools []tools.McpManifest `json:"tools"`
+}
+
+// Used by the client to invoke a tool provided by the server.
+type CallToolRequest struct {
+	jsonrpc.Request
+	Params struct {
+		Name      string         `json:"name"`
+		Arguments map[string]any `json:"arguments,omitempty"`
+	} `json:"params,omitempty"`
+}
+
+// The sender or recipient of messages and data in a conversation.
+type Role string
+
+const (
+	RoleUser      Role = "user"
+	RoleAssistant Role = "assistant"
+)
+
+// Base for objects that include optional annotations for the client.
+// The client can use annotations to inform how objects are used or displayed
+type Annotated struct {
+	Annotations *struct {
+		// Describes who the intended customer of this object or data is.
+		// It can include multiple entries to indicate content useful for multiple
+		// audiences (e.g., `["user", "assistant"]`).
+		Audience []Role `json:"audience,omitempty"`
+		// Describes how important this data is for operating the server.
+		//
+		// A value of 1 means "most important," and indicates that the data is
+		// effectively required, while 0 means "least important," and indicates that
+		// the data is entirely optional.
+		//
+		// @TJS-type number
+		// @minimum 0
+		// @maximum 1
+		Priority float64 `json:"priority,omitempty"`
+	} `json:"annotations,omitempty"`
+}
+
+// TextContent represents text provided to or from an LLM.
+type TextContent struct {
+	Annotated
+	Type string `json:"type"`
+	// The text content of the message.
+	Text string `json:"text"`
+}
+
+// The server's response to a tool call.
+//
+// Any errors that originate from the tool SHOULD be reported inside the result
+// object, with `isError` set to true, _not_ as an MCP protocol-level error
+// response. Otherwise, the LLM would not be able to see that an error occurred
+// and self-correct.
+//
+// However, any errors in _finding_ the tool, an error indicating that the
+// server does not support tool calls, or any other exceptional conditions,
+// should be reported as an MCP error response.
+type CallToolResult struct {
+	jsonrpc.Result
+	// Could be either a TextContent, ImageContent, or EmbeddedResources
+	// For Toolbox, we will only be sending TextContent
+	Content []TextContent `json:"content"`
+	// Whether the tool call ended in an error.
+	// If not set, this is assumed to be false (the call was successful).
+	//
+	// Any errors that originate from the tool SHOULD be reported inside the result
+	// object, with `isError` set to true, _not_ as an MCP protocol-level error
+	// response. Otherwise, the LLM would not be able to see that an error occurred
+	// and self-correct.
+	//
+	// However, any errors in _finding_ the tool, an error indicating that the
+	// server does not support tool calls, or any other exceptional conditions,
+	// should be reported as an MCP error response.
+	IsError bool `json:"isError,omitempty"`
+	// An optional JSON object that represents the structured result of the tool call.
+	StructuredContent map[string]any `json:"structuredContent,omitempty"`
+}
+
+// Additional properties describing a Tool to clients.
+//
+// NOTE: all properties in ToolAnnotations are **hints**.
+// They are not guaranteed to provide a faithful description of
+// tool behavior (including descriptive properties like `title`).
+//
+// Clients should never make tool use decisions based on ToolAnnotations
+// received from untrusted servers.
+type ToolAnnotations struct {
+	// A human-readable title for the tool.
+	Title string `json:"title,omitempty"`
+	// If true, the tool does not modify its environment.
+	// Default: false
+	ReadOnlyHint bool `json:"readOnlyHint,omitempty"`
+	// If true, the tool may perform destructive updates to its environment.
+	// If false, the tool performs only additive updates.
+	// (This property is meaningful only when `readOnlyHint == false`)
+	// Default: true
+	DestructiveHint bool `json:"destructiveHint,omitempty"`
+	// If true, calling the tool repeatedly with the same arguments
+	// will have no additional effect on the its environment.
+	// (This property is meaningful only when `readOnlyHint == false`)
+	// Default: false
+	IdempotentHint bool `json:"idempotentHint,omitempty"`
+	// If true, this tool may interact with an "open world" of external
+	// entities. If false, the tool's domain of interaction is closed.
+	// For example, the world of a web search tool is open, whereas that
+	// of a memory tool is not.
+	// Default: true
+	OpenWorldHint bool `json:"openWorldHint,omitempty"`
+}

internal/server/mcp_test.go

@@ -36,6 +36,7 @@ import (
 const jsonrpcVersion = "2.0"
 const protocolVersion20241105 = "2024-11-05"
 const protocolVersion20250326 = "2025-03-26"
+const protocolVersion20250618 = "2025-06-18"
 const serverName = "Toolbox"
 
 var tool1InputSchema = map[string]any{
@@ -254,7 +255,7 @@ func TestMcpEndpoint(t *testing.T) {
 		initWant map[string]any
 	}{
 		{
-			name:     "verson 2024-11-05",
+			name:     "version 2024-11-05",
 			protocol: protocolVersion20241105,
 			idHeader: false,
 			initWant: map[string]any{
@@ -270,7 +271,7 @@ func TestMcpEndpoint(t *testing.T) {
 			},
 		},
 		{
-			name:     "verson 2025-03-26",
+			name:     "version 2025-03-26",
 			protocol: protocolVersion20250326,
 			idHeader: true,
 			initWant: map[string]any{
@@ -285,6 +286,22 @@ func TestMcpEndpoint(t *testing.T) {
 				},
 			},
 		},
+		{
+			name:     "version 2025-06-18",
+			protocol: protocolVersion20250618,
+			idHeader: false,
+			initWant: map[string]any{
+				"jsonrpc": "2.0",
+				"id":      "mcp-initialize",
+				"result": map[string]any{
+					"protocolVersion": "2025-06-18",
+					"capabilities": map[string]any{
+						"tools": map[string]any{"listChanged": false},
+					},
+					"serverInfo": map[string]any{"name": serverName, "version": fakeVersionString},
+				},
+			},
+		},
 	}
 	for _, vtc := range versTestCases {
 		t.Run(vtc.name, func(t *testing.T) {
@@ -295,6 +312,10 @@ func TestMcpEndpoint(t *testing.T) {
 				header["Mcp-Session-Id"] = sessionId
 			}
 
+			if vtc.protocol == protocolVersion20250618 {
+				header["MCP-Protocol-Version"] = vtc.protocol
+			}
+
 			testCases := []struct {
 				name  string
 				url   string
@@ -481,7 +502,7 @@ func TestMcpEndpoint(t *testing.T) {
 						t.Fatalf("unexpected error during marshaling of body")
 					}
 
-					if vtc.protocol == protocolVersion20250326 && len(header) == 0 {
+					if vtc.protocol != protocolVersion20241105 && len(header) == 0 {
 						t.Fatalf("header is missing")
 					}
 
@@ -514,6 +535,33 @@ func TestMcpEndpoint(t *testing.T) {
 	}
 }
 
+func TestInvalidProtocolVersionHeader(t *testing.T) {
+	toolsMap, toolsets := map[string]tools.Tool{}, map[string]tools.Toolset{}
+	r, shutdown := setUpServer(t, "mcp", toolsMap, toolsets)
+	defer shutdown()
+	ts := runServer(r, false)
+	defer ts.Close()
+
+	header := map[string]string{}
+	header["MCP-Protocol-Version"] = "foo"
+
+	resp, body, err := runRequest(ts, http.MethodPost, "/", nil, header)
+	if resp.Status != "400 Bad Request" {
+		t.Fatalf("unexpected status: %s", resp.Status)
+	}
+	var got map[string]any
+	if err := json.Unmarshal(body, &got); err != nil {
+		t.Fatalf("unexpected error unmarshalling body: %s", err)
+	}
+	want := "invalid protocol version: foo"
+	if got["error"] != want {
+		t.Fatalf("unexpected error message: got %s, want %s", got["error"], want)
+	}
+	if err != nil {
+		t.Fatalf("unexpected error during request: %s", err)
+	}
+}
+
 func TestDeleteEndpoint(t *testing.T) {
 	toolsMap, toolsets := map[string]tools.Tool{}, map[string]tools.Toolset{}
 	r, shutdown := setUpServer(t, "mcp", toolsMap, toolsets)