Strip _meta.ui when client lacks UI capability

Per the MCP Apps 2026-01-26 spec, servers SHOULD check client capabilities
before advertising UI-enabled tools. Extend the inventory strip gate to
remove _meta.ui not only when the feature flag is off, but also when the
request context explicitly reports the client lacks UI support
(HasUISupport returns supported=false, ok=true).

When the capability is unknown (ok=false, e.g. stdio paths), fall through
to the existing feature-flag gate so existing behaviour is preserved.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: 2 people

pkg/http/handler_test.go

@@ -904,3 +904,44 @@ func TestInsidersRoutePreservesUIMeta(t *testing.T) {
 	require.False(t, plainEnabled, "FF should be off for non-insiders ctx")
 	require.Len(t, plainTools, 1)
 }
+
+// TestUIMetaStrippedWhenClientLacksCapability verifies that even on the
+// /insiders path (where the feature flag is on), UI metadata is stripped from
+// tools/list responses when the client did NOT advertise the
+// io.modelcontextprotocol/ui extension capability. Per the 2026-01-26 MCP
+// Apps spec, servers SHOULD check client capabilities before exposing
+// UI-enabled tools.
+func TestUIMetaStrippedWhenClientLacksCapability(t *testing.T) {
+	const uiURI = "ui://test/widget"
+	uiTool := mockTool("with_ui", "repos", true)
+	uiTool.Tool.Meta = mcp.Meta{"ui": map[string]any{"resourceUri": uiURI}}
+
+	checker := createHTTPFeatureChecker(nil, false)
+	build := func() *inventory.Inventory {
+		inv, err := inventory.NewBuilder().
+			SetTools([]inventory.ServerTool{uiTool}).
+			WithFeatureChecker(checker).
+			WithToolsets([]string{"all"}).
+			Build()
+		require.NoError(t, err)
+		return inv
+	}
+
+	insidersCtx := ghcontext.WithInsidersMode(context.Background(), true)
+	withoutUICap := ghcontext.WithUISupport(insidersCtx, false)
+	withUICap := ghcontext.WithUISupport(insidersCtx, true)
+
+	stripped := build().ToolsForRegistration(withoutUICap)
+	require.Len(t, stripped, 1)
+	require.Nil(t, stripped[0].Tool.Meta["ui"], "_meta.ui should be stripped when client lacks UI capability")
+
+	preserved := build().ToolsForRegistration(withUICap)
+	require.Len(t, preserved, 1)
+	require.NotNil(t, preserved[0].Tool.Meta["ui"], "_meta.ui should be preserved when client advertises UI capability")
+	require.Equal(t, uiURI, preserved[0].Tool.Meta["ui"].(map[string]any)["resourceUri"])
+
+	// Unknown capability falls through to the FF gate (insiders ctx → kept).
+	unknown := build().ToolsForRegistration(insidersCtx)
+	require.Len(t, unknown, 1)
+	require.NotNil(t, unknown[0].Tool.Meta["ui"], "_meta.ui should be preserved when capability is unknown and FF is on")
+}

pkg/inventory/registry.go

@@ -7,6 +7,7 @@ import (
 	"slices"
 	"sort"
 
+	ghcontext "github.com/github/github-mcp-server/pkg/context"
 	"github.com/modelcontextprotocol/go-sdk/mcp"
 )
 
@@ -169,26 +170,50 @@ func (r *Inventory) ToolsetDescriptions() map[ToolsetID]string {
 
 // ToolsForRegistration returns AvailableTools(ctx) post-processed exactly as
 // RegisterTools would expose them: with MCP Apps UI metadata stripped when
-// the remote_mcp_ui_apps feature flag is not enabled in ctx. Useful for
-// documentation generators and diagnostics that need the same view of the
-// tool surface the server would register.
+// the client cannot consume it. Useful for documentation generators and
+// diagnostics that need the same view of the tool surface the server would
+// register.
+//
+// The strip applies when EITHER of the following is true:
+//
+//   - The remote_mcp_ui_apps feature flag is not enabled in ctx (server-side gate).
+//   - The client explicitly did not advertise the io.modelcontextprotocol/ui
+//     extension capability (per the 2026-01-26 MCP Apps spec, servers SHOULD
+//     check client capabilities before exposing UI-enabled tools). When the
+//     capability is unknown (e.g. stdio paths that do not populate the
+//     context flag) the feature-flag gate is the sole source of truth.
 func (r *Inventory) ToolsForRegistration(ctx context.Context) []ServerTool {
 	tools := r.AvailableTools(ctx)
-	if !r.checkFeatureFlag(ctx, mcpAppsFeatureFlag) {
+	if shouldStripMCPAppsMetadata(ctx, r.checkFeatureFlag(ctx, mcpAppsFeatureFlag)) {
 		tools = stripMCPAppsMetadata(tools)
 	}
 	return tools
 }
 
+// shouldStripMCPAppsMetadata centralises the strip decision so the same logic
+// is exercised by tests and by RegisterTools.
+func shouldStripMCPAppsMetadata(ctx context.Context, featureFlagEnabled bool) bool {
+	if !featureFlagEnabled {
+		return true
+	}
+	// Feature flag is on. Respect the client capability if it is known.
+	if supported, ok := ghcontext.HasUISupport(ctx); ok && !supported {
+		return true
+	}
+	return false
+}
+
 // RegisterTools registers all available tools with the server using the provided dependencies.
-// The context is used for feature flag evaluation.
+// The context is used for feature flag evaluation and client capability checks.
 //
 // MCP Apps UI metadata (`_meta.ui`) is stripped from the registered tools
-// when the MCP Apps feature flag is not enabled for this request. The strip
-// happens here (rather than at Build() time) so the per-request context is
-// in scope — HTTP feature checkers that read insiders mode or user identity
-// from ctx would otherwise see context.Background() and falsely report the
-// flag off, even when the actual request arrived on the /insiders route.
+// when either the MCP Apps feature flag is not enabled for this request, or
+// the client did not advertise the io.modelcontextprotocol/ui extension. The
+// strip happens here (rather than at Build() time) so the per-request
+// context is in scope — HTTP feature checkers that read insiders mode or
+// user identity from ctx would otherwise see context.Background() and
+// falsely report the flag off, even when the actual request arrived on the
+// /insiders route.
 func (r *Inventory) RegisterTools(ctx context.Context, s *mcp.Server, deps any) {
 	for _, tool := range r.ToolsForRegistration(ctx) {
 		tool.RegisterFunc(s, deps)

pkg/inventory/registry_test.go

@@ -6,6 +6,7 @@ import (
 	"fmt"
 	"testing"
 
+	ghcontext "github.com/github/github-mcp-server/pkg/context"
 	"github.com/modelcontextprotocol/go-sdk/mcp"
 	"github.com/stretchr/testify/require"
 )
@@ -2211,7 +2212,7 @@ func captureRegisteredTools(ctx context.Context, t *testing.T, reg *Inventory) [
 		toolCopy := tools[i].Tool
 		out = append(out, &toolCopy)
 	}
-	if !reg.checkFeatureFlag(ctx, mcpAppsFeatureFlag) {
+	if shouldStripMCPAppsMetadata(ctx, reg.checkFeatureFlag(ctx, mcpAppsFeatureFlag)) {
 		for _, tt := range out {
 			delete(tt.Meta, "ui")
 			if len(tt.Meta) == 0 {
@@ -2221,3 +2222,55 @@ func captureRegisteredTools(ctx context.Context, t *testing.T, reg *Inventory) [
 	}
 	return out
 }
+
+// TestShouldStripMCPAppsMetadata verifies the spec-conformant strip decision:
+// strip when the feature flag is off, OR when the client explicitly does not
+// advertise the io.modelcontextprotocol/ui extension.
+func TestShouldStripMCPAppsMetadata(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name     string
+		setupCtx func() context.Context
+		ffOn     bool
+		want     bool
+	}{
+		{
+			name:     "FF off, capability unknown -> strip",
+			setupCtx: context.Background,
+			ffOn:     false,
+			want:     true,
+		},
+		{
+			name:     "FF off, capability present -> strip (FF wins)",
+			setupCtx: func() context.Context { return ghcontext.WithUISupport(context.Background(), true) },
+			ffOn:     false,
+			want:     true,
+		},
+		{
+			name:     "FF on, capability unknown -> keep",
+			setupCtx: context.Background,
+			ffOn:     true,
+			want:     false,
+		},
+		{
+			name:     "FF on, capability present -> keep",
+			setupCtx: func() context.Context { return ghcontext.WithUISupport(context.Background(), true) },
+			ffOn:     true,
+			want:     false,
+		},
+		{
+			name:     "FF on, capability explicitly absent -> strip",
+			setupCtx: func() context.Context { return ghcontext.WithUISupport(context.Background(), false) },
+			ffOn:     true,
+			want:     true,
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			got := shouldStripMCPAppsMetadata(tc.setupCtx(), tc.ffOn)
+			require.Equal(t, tc.want, got)
+		})
+	}
+}