Merge branch 'main' into envvariable

2026-01-10 07:58:12 -05:00 · 2025-07-16 11:50:21 +00:00
parent 6f569bc950 ed5ef4caea
commit e2ec345e4a
13 changed files with 771 additions and 16 deletions
--- a/README.md
+++ b/README.md
@@ -4,6 +4,7 @@

 [![Docs](https://img.shields.io/badge/docs-MCP_Toolbox-blue)](https://googleapis.github.io/genai-toolbox/)
 [![Discord](https://img.shields.io/badge/Discord-%235865F2.svg?style=flat&logo=discord&logoColor=white)](https://discord.gg/Dmm69peqjh)
+[![Medium](https://img.shields.io/badge/Medium-12100E?style=flat&logo=medium&logoColor=white)](https://medium.com/@mcp_toolbox)
 [![Go Report Card](https://goreportcard.com/badge/github.com/googleapis/genai-toolbox)](https://goreportcard.com/report/github.com/googleapis/genai-toolbox)

 > [!NOTE]
--- a/cmd/root.go
+++ b/cmd/root.go
@@ -65,6 +65,7 @@ import (
 	_ "github.com/googleapis/genai-toolbox/internal/tools/spanner/spannersql"
 	_ "github.com/googleapis/genai-toolbox/internal/tools/sqlitesql"
 	_ "github.com/googleapis/genai-toolbox/internal/tools/utility/envvariable"
+	_ "github.com/googleapis/genai-toolbox/internal/tools/utility/wait"
 	_ "github.com/googleapis/genai-toolbox/internal/tools/valkey"

 	"github.com/spf13/cobra"
--- a/docs/en/how-to/connect_via_mcp.md
+++ b/docs/en/how-to/connect_via_mcp.md
@@ -20,8 +20,9 @@ The native SDKs can be combined with MCP clients in many cases.

 Toolbox currently supports the following versions of MCP specification:

-* [2024-11-05](https://modelcontextprotocol.io/specification/2024-11-05)
+* [2025-06-18](https://modelcontextprotocol.io/specification/2025-06-18)
 * [2025-03-26](https://modelcontextprotocol.io/specification/2025-03-26)
+* [2024-11-05](https://modelcontextprotocol.io/specification/2024-11-05)

 ### Toolbox AuthZ/AuthN Not Supported by MCP

--- a/docs/en/resources/tools/utility/wait.md
+++ b/docs/en/resources/tools/utility/wait.md
@@ -0,0 +1,37 @@
+---
+title: "wait"
+type: docs
+weight: 1
+description: > 
+  A "wait" tool pauses execution for a specified duration.
+aliases:
+- /resources/tools/utility/wait
+---
+
+## About
+
+A `wait` tool pauses execution for a specified duration. This can be useful in workflows where a delay is needed between steps.
+
+`wait` takes one input parameter `duration` which is a string representing the time to wait (e.g., "10s", "2m", "1h").
+
+{{% notice info %}} 
+This tool is intended for developer assistant workflows with human-in-the-loop and shouldn't be used for production agents.
+{{% /notice %}}
+
+## Example
+
+```yaml
+tools:
+  wait_for_tool:
+    kind: wait
+    description: Use this tool to pause execution for a specified duration.
+    timeout: 30s
+```
+
+## Reference
+
+| **field**   |                  **type**                  | **required** | **description**                                                                                  |
+|-------------|:------------------------------------------:|:------------:|--------------------------------------------------------------------------------------------------|
+| kind        |                   string                   |     true     | Must be "wait".                                                                     |
+| description |                   string                   |     true     | Description of the tool that is passed to the LLM.                                               |
+| timeout     |                   string                   |     true     | The default duration the tool can wait for.                                                      |
--- a/internal/server/mcp.go
+++ b/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 {
--- a/internal/server/mcp/mcp.go
+++ b/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)
+}
--- a/internal/server/mcp/util/lifecycle.go
+++ b/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"`
 }
--- a/internal/server/mcp/v20250618/method.go
+++ b/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
+}
--- a/internal/server/mcp/v20250618/types.go
+++ b/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"`
+}
--- a/internal/server/mcp_test.go
+++ b/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)
--- a/internal/tools/utility/wait/wait.go
+++ b/internal/tools/utility/wait/wait.go
@@ -0,0 +1,120 @@
+// 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 wait
+
+import (
+	"context"
+	"fmt"
+	"time"
+
+	yaml "github.com/goccy/go-yaml"
+	"github.com/googleapis/genai-toolbox/internal/sources"
+	"github.com/googleapis/genai-toolbox/internal/tools"
+)
+
+const kind string = "wait"
+
+func init() {
+	if !tools.Register(kind, newConfig) {
+		panic(fmt.Sprintf("tool kind %q already registered", kind))
+	}
+}
+
+func newConfig(ctx context.Context, name string, decoder *yaml.Decoder) (tools.ToolConfig, error) {
+	actual := Config{Name: name}
+	if err := decoder.DecodeContext(ctx, &actual); err != nil {
+		return nil, err
+	}
+	return actual, nil
+}
+
+type Config struct {
+	Name         string   `yaml:"name" validate:"required"`
+	Kind         string   `yaml:"kind" validate:"required"`
+	Description  string   `yaml:"description" validate:"required"`
+	Timeout      string   `yaml:"timeout" validate:"required"`
+	AuthRequired []string `yaml:"authRequired"`
+}
+
+var _ tools.ToolConfig = Config{}
+
+func (cfg Config) ToolConfigKind() string {
+	return kind
+}
+
+func (cfg Config) Initialize(_ map[string]sources.Source) (tools.Tool, error) {
+	durationParameter := tools.NewStringParameter("duration", "The duration to wait for, specified as a string (e.g., '10s', '2m', '1h').")
+	parameters := tools.Parameters{durationParameter}
+
+	mcpManifest := tools.McpManifest{
+		Name:        cfg.Name,
+		Description: cfg.Description,
+		InputSchema: parameters.McpManifest(),
+	}
+
+	t := Tool{
+		Name:        cfg.Name,
+		Kind:        kind,
+		Parameters:  parameters,
+		manifest:    tools.Manifest{Description: cfg.Description, Parameters: parameters.Manifest(), AuthRequired: cfg.AuthRequired},
+		mcpManifest: mcpManifest,
+	}
+	return t, nil
+}
+
+// validate interface
+var _ tools.Tool = Tool{}
+
+type Tool struct {
+	Name        string
+	Kind        string
+	Parameters  tools.Parameters
+	manifest    tools.Manifest
+	mcpManifest tools.McpManifest
+}
+
+func (t Tool) Invoke(ctx context.Context, params tools.ParamValues) ([]any, error) {
+	paramsMap := params.AsMap()
+
+	durationStr, ok := paramsMap["duration"].(string)
+	if !ok {
+		return nil, fmt.Errorf("duration parameter is not a string")
+	}
+
+	totalDuration, err := time.ParseDuration(durationStr)
+	if err != nil {
+		return nil, fmt.Errorf("invalid duration format: %w", err)
+	}
+
+	time.Sleep(totalDuration)
+
+	return []any{fmt.Sprintf("Wait for %v completed successfully.", totalDuration)}, nil
+}
+
+func (t Tool) ParseParams(data map[string]any, claims map[string]map[string]any) (tools.ParamValues, error) {
+	return tools.ParseParams(t.Parameters, data, claims)
+}
+
+func (t Tool) Manifest() tools.Manifest {
+	return t.manifest
+}
+
+func (t Tool) McpManifest() tools.McpManifest {
+	return t.mcpManifest
+}
+
+func (t Tool) Authorized(verifiedAuthServices []string) bool {
+	return true
+}
--- a/internal/tools/utility/wait/wait_test.go
+++ b/internal/tools/utility/wait/wait_test.go
@@ -0,0 +1,75 @@
+// 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 wait_test
+
+import (
+	"testing"
+
+	yaml "github.com/goccy/go-yaml"
+	"github.com/google/go-cmp/cmp"
+	"github.com/googleapis/genai-toolbox/internal/server"
+	"github.com/googleapis/genai-toolbox/internal/testutils"
+
+	wait "github.com/googleapis/genai-toolbox/internal/tools/utility/wait"
+)
+
+func TestParseFromYamlWait(t *testing.T) {
+	ctx, err := testutils.ContextWithNewLogger()
+	if err != nil {
+		t.Fatalf("unexpected error: %s", err)
+	}
+	tcs := []struct {
+		desc string
+		in   string
+		want server.ToolConfigs
+	}{
+		{
+			desc: "basic example",
+			in: `
+			tools:
+				example_tool:
+					kind: wait
+					description: some description
+					timeout: 10s
+					authRequired:
+						- my-google-auth-service
+			`,
+			want: server.ToolConfigs{
+				"example_tool": wait.Config{
+					Name:         "example_tool",
+					Kind:         "wait",
+					Description:  "some description",
+					Timeout:      "10s",
+					AuthRequired: []string{"my-google-auth-service"},
+				},
+			},
+		},
+	}
+	for _, tc := range tcs {
+		t.Run(tc.desc, func(t *testing.T) {
+			got := struct {
+				Tools server.ToolConfigs `yaml:"tools"`
+			}{}
+			// Parse contents
+			err := yaml.UnmarshalContext(ctx, testutils.FormatYaml(tc.in), &got)
+			if err != nil {
+				t.Fatalf("unable to unmarshal: %s", err)
+			}
+			if diff := cmp.Diff(tc.want, got.Tools); diff != "" {
+				t.Fatalf("incorrect parse: diff %v", diff)
+			}
+		})
+	}
+}
--- a/tests/utility/wait_integration_test.go
+++ b/tests/utility/wait_integration_test.go
@@ -0,0 +1,118 @@
+// 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 utility
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"io"
+	"net/http"
+	"regexp"
+	"testing"
+	"time"
+
+	"github.com/googleapis/genai-toolbox/internal/testutils"
+	"github.com/googleapis/genai-toolbox/tests"
+)
+
+func RunWaitTool(t *testing.T) {
+	ctx, cancel := context.WithTimeout(context.Background(), time.Minute)
+	defer cancel()
+
+	args := []string{"--port", "5001"}
+
+	toolsFile := map[string]any{
+		"tools": map[string]any{
+			"my-wait-for-tool": map[string]any{
+				"kind":        "wait",
+				"description": "Wait for a specified duration.",
+				"timeout":     "30s",
+			},
+		},
+	}
+	cmd, cleanup, err := tests.StartCmd(ctx, toolsFile, args...)
+	if err != nil {
+		t.Fatalf("command initialization returned an error: %s", err)
+	}
+	defer cleanup()
+
+	waitCtx, cancel := context.WithTimeout(ctx, 10*time.Second)
+	defer cancel()
+	out, err := testutils.WaitForString(waitCtx, regexp.MustCompile(`Server ready to serve`), cmd.Out)
+	if err != nil {
+		t.Logf("toolbox command logs: \n%s", out)
+		t.Fatalf("toolbox didn't start successfully: %s", err)
+	}
+
+	invokeTcs := []struct {
+		name        string
+		api         string
+		requestBody io.Reader
+		want        string
+		isErr       bool
+	}{
+		{
+			name:        "invoke my-wait-for-tool",
+			api:         "http://127.0.0.1:5001/api/tool/my-wait-for-tool/invoke",
+			requestBody: bytes.NewBuffer([]byte(`{"duration": "1s"}`)),
+			want:        `["Wait for 1s completed successfully."]`,
+			isErr:       false,
+		},
+		{
+			name:        "invoke my-wait-for-tool with invalid duration",
+			api:         "http://127.0.0.1:5001/api/tool/my-wait-for-tool/invoke",
+			requestBody: bytes.NewBuffer([]byte(`{"duration": "invalid"}`)),
+			isErr:       true,
+		},
+	}
+	for _, tc := range invokeTcs {
+		t.Run(tc.name, func(t *testing.T) {
+			req, err := http.NewRequest(http.MethodPost, tc.api, tc.requestBody)
+			if err != nil {
+				t.Fatalf("unable to create request: %s", err)
+			}
+			req.Header.Add("Content-type", "application/json")
+			resp, err := http.DefaultClient.Do(req)
+			if err != nil {
+				t.Fatalf("unable to send request: %s", err)
+			}
+			defer resp.Body.Close()
+
+			if resp.StatusCode != http.StatusOK {
+				if tc.isErr {
+					return
+				}
+				bodyBytes, _ := io.ReadAll(resp.Body)
+				t.Fatalf("response status code is not 200, got %d: %s", resp.StatusCode, string(bodyBytes))
+			}
+
+			var body map[string]interface{}
+			err = json.NewDecoder(resp.Body).Decode(&body)
+			if err != nil {
+				t.Fatalf("error parsing response body")
+			}
+
+			got, ok := body["result"].(string)
+			if !ok {
+				t.Fatalf("unable to find result in response body")
+			}
+
+			if got != tc.want {
+				t.Fatalf("unexpected value: got %q, want %q", got, tc.want)
+			}
+		})
+	}
+}