feat(api): support elicitation from tool calls (#804)

* feat(mcp): support elicitation from tool calls

Signed-off-by: Calum Murray <cmurray@redhat.com>

* cleanup: address review comments

Signed-off-by: Calum Murray <cmurray@redhat.com>

---------

Signed-off-by: Calum Murray <cmurray@redhat.com>

Author: Cali0707

internal/test/mcp.go

@@ -25,6 +25,7 @@ type mcpClientConfig struct {
 	clientInfo           *mcp.Implementation
 	endpoint             string
 	allowConnectionError bool
+	elicitationHandler   func(context.Context, *mcp.ElicitRequest) (*mcp.ElicitResult, error)
 }
 
 // httpHeaderOption sets custom HTTP headers
@@ -95,6 +96,22 @@ func WithAllowConnectionError() McpClientOption {
 	return allowConnectionErrorOption{}
 }
 
+// elicitationHandlerOption sets a custom elicitation handler on the MCP client
+type elicitationHandlerOption struct {
+	handler func(context.Context, *mcp.ElicitRequest) (*mcp.ElicitResult, error)
+}
+
+func (o elicitationHandlerOption) apply(c *mcpClientConfig) {
+	c.elicitationHandler = o.handler
+}
+
+// WithElicitationHandler sets an elicitation handler on the MCP client.
+// When set, the client advertises elicitation support and the handler is invoked
+// when the server sends an elicitation request during tool execution.
+func WithElicitationHandler(handler func(context.Context, *mcp.ElicitRequest) (*mcp.ElicitResult, error)) McpClientOption {
+	return elicitationHandlerOption{handler: handler}
+}
+
 // headerRoundTripper injects HTTP headers into requests
 type headerRoundTripper struct {
 	base    http.RoundTripper
@@ -184,6 +201,7 @@ func NewMcpClient(t *testing.T, mcpHttpServer http.Handler, options ...McpClient
 
 	// Create go-sdk client with notification handlers
 	clientOptions := &mcp.ClientOptions{
+		ElicitationHandler: cfg.elicitationHandler,
 		ToolListChangedHandler: func(_ context.Context, req *mcp.ToolListChangedRequest) {
 			ret.notifications.capture(&CapturedNotification{
 				Method: "notifications/tools/list_changed",

pkg/api/prompts.go

@@ -87,6 +87,7 @@ type PromptHandlerParams struct {
 	ExtendedConfigProvider
 	KubernetesClient
 	PromptCallRequest
+	Elicitor
 }
 
 // PromptHandlerFunc is a function that handles prompt execution

pkg/api/toolsets.go

@@ -103,10 +103,38 @@ type ToolHandlerParams struct {
 	KubernetesClient
 	ToolCallRequest
 	ListOutput output.Output
+	Elicitor
 }
 
 type ToolHandlerFunc func(params ToolHandlerParams) (*ToolCallResult, error)
 
+// Elicitor provides a mechanism for tools and prompts to request additional information
+// from the user during execution via the MCP elicitation protocol.
+// The elicitation request is forwarded to the MCP client, which presents a form to the user.
+// See MCP specification: https://modelcontextprotocol.io/specification/2025-11-25/client/elicitation
+type Elicitor interface {
+	Elicit(ctx context.Context, message string, requestedSchema *jsonschema.Schema) (*ElicitResult, error)
+}
+
+// ElicitAction constants define the possible user responses to an elicitation request.
+// See MCP specification: https://modelcontextprotocol.io/specification/2025-11-25/client/elicitation
+const (
+	// ElicitActionAccept indicates the user submitted the form with content.
+	ElicitActionAccept = "accept"
+	// ElicitActionDecline indicates the user explicitly declined the request.
+	ElicitActionDecline = "decline"
+	// ElicitActionCancel indicates the user dismissed the form without making a choice.
+	ElicitActionCancel = "cancel"
+)
+
+// ElicitResult represents the user's response to an elicitation request.
+type ElicitResult struct {
+	// Action is one of ElicitActionAccept, ElicitActionDecline, or ElicitActionCancel.
+	Action string
+	// Content contains the submitted form data. Only populated when Action is ElicitActionAccept.
+	Content map[string]any
+}
+
 type Tool struct {
 	// The name of the tool.
 	// Intended for programmatic or logical use, but used as a display name in past

pkg/mcp/elicit.go

@@ -0,0 +1,38 @@
+package mcp
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"strings"
+
+	"github.com/containers/kubernetes-mcp-server/pkg/api"
+	"github.com/containers/kubernetes-mcp-server/pkg/mcplog"
+	"github.com/google/jsonschema-go/jsonschema"
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+)
+
+// ErrElicitationNotSupported is returned when the MCP client does not support elicitation.
+// Tool authors can check for this error using errors.Is() to implement fallback behavior.
+var ErrElicitationNotSupported = errors.New("client does not support elicitation")
+
+type sessionElicitor struct{}
+
+var _ api.Elicitor = &sessionElicitor{}
+
+func (s *sessionElicitor) Elicit(ctx context.Context, message string, requestedSchema *jsonschema.Schema) (*api.ElicitResult, error) {
+	session, ok := ctx.Value(mcplog.MCPSessionContextKey).(*mcp.ServerSession)
+	if !ok || session == nil {
+		return nil, fmt.Errorf("no MCP session found in context")
+	}
+
+	result, err := session.Elicit(ctx, &mcp.ElicitParams{Message: message, RequestedSchema: requestedSchema})
+	if err != nil {
+		if strings.Contains(err.Error(), "does not support elicitation") {
+			return nil, fmt.Errorf("%w: %s", ErrElicitationNotSupported, err.Error())
+		}
+		return nil, err
+	}
+
+	return &api.ElicitResult{Action: result.Action, Content: result.Content}, nil
+}

pkg/mcp/elicit_test.go

@@ -0,0 +1,170 @@
+package mcp
+
+import (
+	"context"
+	"errors"
+	"testing"
+
+	"github.com/containers/kubernetes-mcp-server/internal/test"
+	"github.com/containers/kubernetes-mcp-server/pkg/api"
+	"github.com/containers/kubernetes-mcp-server/pkg/toolsets"
+	"github.com/google/jsonschema-go/jsonschema"
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+	"github.com/stretchr/testify/suite"
+	"k8s.io/utils/ptr"
+)
+
+type ElicitationSuite struct {
+	BaseMcpSuite
+	originalToolsets []api.Toolset
+}
+
+func (s *ElicitationSuite) SetupTest() {
+	s.BaseMcpSuite.SetupTest()
+	s.originalToolsets = toolsets.Toolsets()
+}
+
+func (s *ElicitationSuite) TearDownTest() {
+	s.BaseMcpSuite.TearDownTest()
+	toolsets.Clear()
+	for _, toolset := range s.originalToolsets {
+		toolsets.Register(toolset)
+	}
+}
+
+func (s *ElicitationSuite) registerElicitingToolset(handler api.ToolHandlerFunc) {
+	testToolset := &mockElicitToolset{
+		tools: []api.ServerTool{
+			{
+				Tool: api.Tool{
+					Name:        "elicit_test_tool",
+					Description: "Tool that uses elicitation for testing",
+					Annotations: api.ToolAnnotations{
+						ReadOnlyHint: ptr.To(true),
+					},
+					InputSchema: &jsonschema.Schema{
+						Type:       "object",
+						Properties: make(map[string]*jsonschema.Schema),
+					},
+				},
+				Handler: handler,
+			},
+		},
+	}
+
+	toolsets.Clear()
+	toolsets.Register(testToolset)
+	s.Cfg.Toolsets = []string{"elicit-test"}
+}
+
+func (s *ElicitationSuite) TestElicitationAccepted() {
+	s.registerElicitingToolset(func(params api.ToolHandlerParams) (*api.ToolCallResult, error) {
+		result, err := params.Elicit(params.Context, "Please confirm", nil)
+		if err != nil {
+			return nil, err
+		}
+		return api.NewToolCallResult("action="+result.Action+",name="+result.Content["name"].(string), nil), nil
+	})
+
+	s.InitMcpClient(test.WithElicitationHandler(
+		func(_ context.Context, req *mcp.ElicitRequest) (*mcp.ElicitResult, error) {
+			return &mcp.ElicitResult{
+				Action:  "accept",
+				Content: map[string]any{"name": "test-value"},
+			}, nil
+		},
+	))
+
+	toolResult, err := s.CallTool("elicit_test_tool", map[string]any{})
+
+	s.Run("returns accepted elicitation content", func() {
+		s.NoError(err)
+		s.Require().NotNil(toolResult)
+		s.False(toolResult.IsError)
+		s.Require().Len(toolResult.Content, 1)
+		textContent, ok := toolResult.Content[0].(*mcp.TextContent)
+		s.Require().True(ok)
+		s.Equal("action=accept,name=test-value", textContent.Text)
+	})
+}
+
+func (s *ElicitationSuite) TestElicitationDeclined() {
+	s.registerElicitingToolset(func(params api.ToolHandlerParams) (*api.ToolCallResult, error) {
+		result, err := params.Elicit(params.Context, "Please confirm", nil)
+		if err != nil {
+			return nil, err
+		}
+		return api.NewToolCallResult("action="+result.Action, nil), nil
+	})
+
+	s.InitMcpClient(test.WithElicitationHandler(
+		func(_ context.Context, _ *mcp.ElicitRequest) (*mcp.ElicitResult, error) {
+			return &mcp.ElicitResult{Action: "decline"}, nil
+		},
+	))
+
+	toolResult, err := s.CallTool("elicit_test_tool", map[string]any{})
+
+	s.Run("returns declined action", func() {
+		s.NoError(err)
+		s.Require().NotNil(toolResult)
+		s.False(toolResult.IsError)
+		s.Require().Len(toolResult.Content, 1)
+		textContent, ok := toolResult.Content[0].(*mcp.TextContent)
+		s.Require().True(ok)
+		s.Equal("action=decline", textContent.Text)
+	})
+}
+
+func (s *ElicitationSuite) TestElicitationWithUnsupportedClient() {
+	s.registerElicitingToolset(func(params api.ToolHandlerParams) (*api.ToolCallResult, error) {
+		_, err := params.Elicit(params.Context, "Please confirm", nil)
+		if err != nil {
+			if errors.Is(err, ErrElicitationNotSupported) {
+				return api.NewToolCallResult("fallback-result", nil), nil
+			}
+			return nil, err
+		}
+		return api.NewToolCallResult("should-not-reach", nil), nil
+	})
+
+	// No ElicitationHandler = client does not support elicitation
+	s.InitMcpClient()
+
+	toolResult, err := s.CallTool("elicit_test_tool", map[string]any{})
+
+	s.Run("tool handles unsupported elicitation gracefully", func() {
+		s.NoError(err)
+		s.Require().NotNil(toolResult)
+		s.False(toolResult.IsError)
+		s.Require().Len(toolResult.Content, 1)
+		textContent, ok := toolResult.Content[0].(*mcp.TextContent)
+		s.Require().True(ok)
+		s.Equal("fallback-result", textContent.Text)
+	})
+}
+
+// mockElicitToolset is a test toolset that provides tools using the Elicitor interface
+type mockElicitToolset struct {
+	tools []api.ServerTool
+}
+
+func (m *mockElicitToolset) GetName() string {
+	return "elicit-test"
+}
+
+func (m *mockElicitToolset) GetDescription() string {
+	return "Test toolset for elicitation"
+}
+
+func (m *mockElicitToolset) GetTools(_ api.Openshift) []api.ServerTool {
+	return m.tools
+}
+
+func (m *mockElicitToolset) GetPrompts() []api.ServerPrompt {
+	return nil
+}
+
+func TestElicitationSuite(t *testing.T) {
+	suite.Run(t, new(ElicitationSuite))
+}

pkg/mcp/gosdk.go

@@ -52,6 +52,7 @@ func ServerToolToGoSdkTool(s *Server, tool api.ServerTool) (*mcp.Tool, mcp.ToolH
 			KubernetesClient:       k,
 			ToolCallRequest:        toolCallRequest,
 			ListOutput:             s.configuration.ListOutput(),
+			Elicitor:               &sessionElicitor{},
 		})
 		if err != nil {
 			return nil, err

pkg/mcp/prompts_gosdk.go

@@ -60,6 +60,7 @@ func ServerPromptToGoSdkPrompt(s *Server, serverPrompt api.ServerPrompt) (*mcp.P
 			ExtendedConfigProvider: s.configuration,
 			KubernetesClient:       k8s,
 			PromptCallRequest:      &promptCallRequestAdapter{request: request},
+			Elicitor:               &sessionElicitor{},
 		}
 
 		result, err := serverPrompt.Handler(params)