migrate mcp apps support from insiders mode to feature flag with insiders opt-in

Author: mattdholloway

docs/insiders-features.md

@@ -20,25 +20,4 @@ For configuration examples, see the [Server Configuration Guide](./server-config
 
 ---
 
-## MCP Apps
-
-[MCP Apps](https://modelcontextprotocol.io/docs/extensions/apps) is an extension to the Model Context Protocol that enables servers to deliver interactive user interfaces to end users. Instead of returning plain text that the LLM must interpret and relay, tools can render forms, profiles, and dashboards right in the chat using MCP Apps.
-
-This means you can interact with GitHub visually: fill out forms to create issues, see user profiles with avatars, open pull requests — all without leaving your agent chat.
-
-### Supported tools
-
-The following tools have MCP Apps UIs:
-
-| Tool | Description |
-|------|-------------|
-| `get_me` | Displays your GitHub user profile with avatar, bio, and stats in a rich card |
-| `issue_write` | Opens an interactive form to create or update issues |
-| `create_pull_request` | Provides a full PR creation form to create a pull request (or a draft pull request) |
-
-### Client requirements
-
-MCP Apps requires a host that supports the [MCP Apps extension](https://modelcontextprotocol.io/docs/extensions/apps). Currently tested and working with:
-
-- **VS Code Insiders** — enable via the `chat.mcp.apps.enabled` setting
-- **Visual Studio Code** — enable via the `chat.mcp.apps.enabled` setting
+_There are currently no insiders-only features. [MCP Apps](./server-configuration.md#mcp-apps) has graduated to a feature flag (`remote_mcp_ui_apps`) and can be enabled independently._

docs/server-configuration.md

@@ -14,6 +14,7 @@ We currently support the following ways in which the GitHub MCP Server can be co
 | Dynamic Mode | Not available | `--dynamic-toolsets` flag or `GITHUB_DYNAMIC_TOOLSETS` env var |
 | Lockdown Mode | `X-MCP-Lockdown` header | `--lockdown-mode` flag or `GITHUB_LOCKDOWN_MODE` env var |
 | Insiders Mode | `X-MCP-Insiders` header or `/insiders` URL | `--insiders` flag or `GITHUB_INSIDERS` env var |
+| Feature Flags | `X-MCP-Features` header | `--features` flag |
 | Scope Filtering | Always enabled | Always enabled |
 | Server Name/Title | Not available | `GITHUB_MCP_SERVER_NAME` / `GITHUB_MCP_SERVER_TITLE` env vars or `github-mcp-server-config.json` |
 
@@ -390,7 +391,10 @@ Lockdown mode ensures the server only surfaces content in public repositories fr
 
 **Best for:** Users who want early access to experimental features and new tools before they reach general availability.
 
-Insiders Mode unlocks experimental features, such as [MCP Apps](./insiders-features.md#mcp-apps) support. We created this mode to have a way to roll out experimental features and collect feedback. So if you are using Insiders, please don't hesitate to share your feedback with us! Features in Insiders Mode may change, evolve, or be removed based on user feedback. 
+Insiders Mode unlocks experimental features. We created this mode to have a way to roll out experimental features and collect feedback. So if you are using Insiders, please don't hesitate to share your feedback with us! Features in Insiders Mode may change, evolve, or be removed based on user feedback.
+
+> [!NOTE]
+> Insiders mode also enables the `remote_mcp_ui_apps` feature flag for backward compatibility. See [MCP Apps](#mcp-apps) below.
 
 <table>
 <tr><th>Remote Server</th><th>Local Server</th></tr>
@@ -443,6 +447,62 @@ See [Insiders Features](./insiders-features.md) for a full list of what's availa
 
 ---
 
+### MCP Apps
+
+[MCP Apps](https://modelcontextprotocol.io/docs/extensions/apps) is an extension to the Model Context Protocol that enables servers to deliver interactive user interfaces to end users. Instead of returning plain text that the LLM must interpret and relay, tools can render forms, profiles, and dashboards right in the chat.
+
+MCP Apps is controlled by the `remote_mcp_ui_apps` feature flag and can be enabled independently of insiders mode.
+
+**Supported tools:**
+
+| Tool | Description |
+|------|-------------|
+| `get_me` | Displays your GitHub user profile with avatar, bio, and stats in a rich card |
+| `issue_write` | Opens an interactive form to create or update issues |
+| `create_pull_request` | Provides a full PR creation form to create a pull request (or a draft pull request) |
+
+**Client requirements:** MCP Apps requires a host that supports the [MCP Apps extension](https://modelcontextprotocol.io/docs/extensions/apps). Currently tested with VS Code (`chat.mcp.apps.enabled` setting).
+
+<table>
+<tr><th>Remote Server</th><th>Local Server</th></tr>
+<tr valign="top">
+<td>
+
+```json
+{
+  "type": "http",
+  "url": "https://api.githubcopilot.com/mcp/",
+  "headers": {
+    "X-MCP-Features": "remote_mcp_ui_apps"
+  }
+}
+```
+
+</td>
+<td>
+
+```json
+{
+  "type": "stdio",
+  "command": "go",
+  "args": [
+    "run",
+    "./cmd/github-mcp-server",
+    "stdio",
+    "--features=remote_mcp_ui_apps"
+  ],
+  "env": {
+    "GITHUB_PERSONAL_ACCESS_TOKEN": "${input:github_token}"
+  }
+}
+```
+
+</td>
+</tr>
+</table>
+
+---
+
 ### Scope Filtering
 
 **Automatic feature:** The server handles OAuth scopes differently depending on authentication type:

internal/ghmcp/server.go

@@ -8,6 +8,7 @@ import (
 	"net/http"
 	"os"
 	"os/signal"
+	"slices"
 	"strings"
 	"syscall"
 	"time"
@@ -114,8 +115,13 @@ func NewStdioMCPServer(ctx context.Context, cfg github.MCPServerConfig) (*mcp.Se
 		return nil, fmt.Errorf("failed to create GitHub clients: %w", err)
 	}
 
-	// Create feature checker
-	featureChecker := createFeatureChecker(cfg.EnabledFeatures)
+	// Create feature checker — insiders mode transitionally enables remote_mcp_ui_apps
+	enabledFeatures := cfg.EnabledFeatures
+	if cfg.InsidersMode && !slices.Contains(enabledFeatures, github.MCPAppsFeatureFlag) {
+		enabledFeatures = append(slices.Clone(enabledFeatures), github.MCPAppsFeatureFlag)
+	}
+	featureChecker := createFeatureChecker(enabledFeatures)
+	mcpAppsEnabled := slices.Contains(enabledFeatures, github.MCPAppsFeatureFlag)
 
 	// Create dependencies for tool handlers
 	obs, err := observability.NewExporters(cfg.Logger, metrics.NewNoopMetrics())
@@ -145,7 +151,8 @@ func NewStdioMCPServer(ctx context.Context, cfg github.MCPServerConfig) (*mcp.Se
 		WithExcludeTools(cfg.ExcludeTools).
 		WithServerInstructions().
 		WithFeatureChecker(featureChecker).
-		WithInsidersMode(cfg.InsidersMode)
+		WithInsidersMode(cfg.InsidersMode).
+		WithMCPApps(mcpAppsEnabled)
 
 	// Apply token scope filtering if scopes are known (for PAT filtering)
 	if cfg.TokenScopes != nil {
@@ -162,10 +169,11 @@ func NewStdioMCPServer(ctx context.Context, cfg github.MCPServerConfig) (*mcp.Se
 		return nil, fmt.Errorf("failed to create GitHub MCP server: %w", err)
 	}
 
-	// Register MCP App UI resources if available (requires running script/build-ui).
-	// We check availability to allow Insiders mode to work for non-UI features
-	// even when UI assets haven't been built.
-	if cfg.InsidersMode && github.UIAssetsAvailable() {
+	// Register MCP App UI resources if the remote_mcp_ui_apps feature flag is enabled
+	// and UI assets are available (requires running script/build-ui).
+	// We check availability to allow the feature flag to be enabled without
+	// requiring a UI build (graceful degradation).
+	if mcpAppsEnabled && github.UIAssetsAvailable() {
 		github.RegisterUIResources(ghServer)
 	}
 

pkg/github/feature_flags.go

@@ -1,5 +1,11 @@
 package github
 
+// MCPAppsFeatureFlag is the feature flag name that enables MCP Apps
+// (interactive UI forms) for supported tools. When enabled, tools like
+// get_me, issue_write, and create_pull_request can render rich UI via
+// the MCP Apps extension instead of plain text responses.
+const MCPAppsFeatureFlag = "remote_mcp_ui_apps"
+
 // FeatureFlags defines runtime feature toggles that adjust tool behavior.
 type FeatureFlags struct {
 	LockdownMode bool

pkg/github/issues.go

@@ -1073,12 +1073,12 @@ Options are:
 				return utils.NewToolResultError(err.Error()), nil, nil
 			}
 
-			// When insiders mode is enabled and the client supports MCP Apps UI,
+			// When the MCP Apps feature flag is enabled and the client supports MCP Apps UI,
 			// check if this is a UI form submission. The UI sends _ui_submitted=true
 			// to distinguish form submissions from LLM calls.
 			uiSubmitted, _ := OptionalParam[bool](args, "_ui_submitted")
 
-			if deps.GetFlags(ctx).InsidersMode && clientSupportsUI(ctx, req) && !uiSubmitted {
+			if deps.IsFeatureEnabled(ctx, MCPAppsFeatureFlag) && clientSupportsUI(ctx, req) && !uiSubmitted {
 				if method == "update" {
 					// Skip the UI form when a state change is requested because
 					// the form only handles title/body editing and would lose the

pkg/github/issues_test.go

@@ -932,9 +932,9 @@ func Test_CreateIssue(t *testing.T) {
 	}
 }
 
-// Test_IssueWrite_InsidersMode_UIGate verifies the insiders mode UI gate
+// Test_IssueWrite_MCPApps_UIGate verifies the MCP Apps feature flag UI gate
 // behavior: UI clients get a form message, non-UI clients execute directly.
-func Test_IssueWrite_InsidersMode_UIGate(t *testing.T) {
+func Test_IssueWrite_MCPApps_UIGate(t *testing.T) {
 	t.Parallel()
 
 	mockIssue := &github.Issue{
@@ -949,11 +949,17 @@ func Test_IssueWrite_InsidersMode_UIGate(t *testing.T) {
 		PostReposIssuesByOwnerByRepo: mockResponse(t, http.StatusCreated, mockIssue),
 	}))
 
-	deps := BaseDeps{
-		Client:    client,
-		GQLClient: githubv4.NewClient(nil),
-		Flags:     FeatureFlags{InsidersMode: true},
+	mcpAppsChecker := func(_ context.Context, flag string) (bool, error) {
+		return flag == MCPAppsFeatureFlag, nil
 	}
+	deps := NewBaseDeps(
+		client, githubv4.NewClient(nil), nil, nil,
+		translations.NullTranslationHelper,
+		FeatureFlags{},
+		0,
+		mcpAppsChecker,
+		stubExporters(),
+	)
 	handler := serverTool.Handler(deps)
 
 	t.Run("UI client without _ui_submitted returns form message", func(t *testing.T) {
@@ -1066,11 +1072,14 @@ func Test_IssueWrite_InsidersMode_UIGate(t *testing.T) {
 			),
 		))
 
-		closeDeps := BaseDeps{
-			Client:    closeClient,
-			GQLClient: closeGQLClient,
-			Flags:     FeatureFlags{InsidersMode: true},
-		}
+		closeDeps := NewBaseDeps(
+			closeClient, closeGQLClient, nil, nil,
+			translations.NullTranslationHelper,
+			FeatureFlags{},
+			0,
+			mcpAppsChecker,
+			stubExporters(),
+		)
 		closeHandler := serverTool.Handler(closeDeps)
 
 		request := createMCPRequestWithSession(t, ClientNameVSCodeInsiders, true, map[string]any{

pkg/github/pullrequests.go

@@ -601,12 +601,12 @@ func CreatePullRequest(t translations.TranslationHelperFunc) inventory.ServerToo
 				return utils.NewToolResultError(err.Error()), nil, nil
 			}
 
-			// When insiders mode is enabled and the client supports MCP Apps UI,
+			// When the MCP Apps feature flag is enabled and the client supports MCP Apps UI,
 			// check if this is a UI form submission. The UI sends _ui_submitted=true
 			// to distinguish form submissions from LLM calls.
 			uiSubmitted, _ := OptionalParam[bool](args, "_ui_submitted")
 
-			if deps.GetFlags(ctx).InsidersMode && clientSupportsUI(ctx, req) && !uiSubmitted {
+			if deps.IsFeatureEnabled(ctx, MCPAppsFeatureFlag) && clientSupportsUI(ctx, req) && !uiSubmitted {
 				return utils.NewToolResultText(fmt.Sprintf("Ready to create a pull request in %s/%s. IMPORTANT: The PR has NOT been created yet. Do NOT tell the user the PR was created. The user MUST click Submit in the form to create it.", owner, repo)), nil, nil
 			}
 

pkg/github/pullrequests_test.go

@@ -2312,9 +2312,9 @@ func Test_CreatePullRequest(t *testing.T) {
 	}
 }
 
-// Test_CreatePullRequest_InsidersMode_UIGate verifies the insiders mode UI gate
+// Test_CreatePullRequest_MCPApps_UIGate verifies the MCP Apps feature flag UI gate
 // behavior: UI clients get a form message, non-UI clients execute directly.
-func Test_CreatePullRequest_InsidersMode_UIGate(t *testing.T) {
+func Test_CreatePullRequest_MCPApps_UIGate(t *testing.T) {
 	t.Parallel()
 
 	mockPR := &github.PullRequest{
@@ -2332,11 +2332,17 @@ func Test_CreatePullRequest_InsidersMode_UIGate(t *testing.T) {
 		PostReposPullsByOwnerByRepo: mockResponse(t, http.StatusCreated, mockPR),
 	}))
 
-	deps := BaseDeps{
-		Client:    client,
-		GQLClient: githubv4.NewClient(nil),
-		Flags:     FeatureFlags{InsidersMode: true},
+	mcpAppsChecker := func(_ context.Context, flag string) (bool, error) {
+		return flag == MCPAppsFeatureFlag, nil
 	}
+	deps := NewBaseDeps(
+		client, githubv4.NewClient(nil), nil, nil,
+		translations.NullTranslationHelper,
+		FeatureFlags{},
+		0,
+		mcpAppsChecker,
+		stubExporters(),
+	)
 	handler := serverTool.Handler(deps)
 
 	t.Run("UI client without _ui_submitted returns form message", func(t *testing.T) {

pkg/http/handler.go

@@ -5,6 +5,7 @@ import (
 	"errors"
 	"log/slog"
 	"net/http"
+	"slices"
 
 	ghcontext "github.com/github/github-mcp-server/pkg/context"
 	"github.com/github/github-mcp-server/pkg/github"
@@ -261,6 +262,19 @@ func InventoryFiltersForRequest(r *http.Request, builder *inventory.Builder) *in
 		builder = builder.WithReadOnly(true)
 	}
 
+	insiders := ghcontext.IsInsidersMode(ctx)
+	if insiders {
+		builder = builder.WithInsidersMode(true)
+	}
+
+	// Enable MCP Apps if the feature flag is present in the request headers
+	// or if insiders mode is active (transitional: insiders implies remote_mcp_ui_apps).
+	headerFeatures := ghcontext.GetHeaderFeatures(ctx)
+	mcpApps := slices.Contains(headerFeatures, github.MCPAppsFeatureFlag) || insiders
+	if mcpApps {
+		builder = builder.WithMCPApps(true)
+	}
+
 	toolsets := ghcontext.GetToolsets(ctx)
 	tools := ghcontext.GetTools(ctx)
 

pkg/http/server.go

@@ -27,7 +27,9 @@ import (
 
 // knownFeatureFlags are the feature flags that can be enabled via X-MCP-Features header.
 // Only these flags are accepted from headers.
-var knownFeatureFlags = []string{}
+var knownFeatureFlags = []string{
+	github.MCPAppsFeatureFlag,
+}
 
 type ServerConfig struct {
 	// Version of the server
@@ -212,7 +214,8 @@ func initGlobalToolScopeMap(t translations.TranslationHelperFunc) error {
 }
 
 // createHTTPFeatureChecker creates a feature checker that reads header features from context
-// and validates them against the knownFeatureFlags whitelist
+// and validates them against the knownFeatureFlags whitelist.
+// It also handles transitional behavior where insiders mode implies remote_mcp_ui_apps.
 func createHTTPFeatureChecker() inventory.FeatureFlagChecker {
 	// Pre-compute whitelist as set for O(1) lookup
 	knownSet := make(map[string]bool, len(knownFeatureFlags))
@@ -224,6 +227,10 @@ func createHTTPFeatureChecker() inventory.FeatureFlagChecker {
 		if knownSet[flag] && slices.Contains(ghcontext.GetHeaderFeatures(ctx), flag) {
 			return true, nil
 		}
+		// Transitional: insiders mode implies remote_mcp_ui_apps feature flag
+		if flag == github.MCPAppsFeatureFlag && ghcontext.IsInsidersMode(ctx) {
+			return true, nil
+		}
 		return false, nil
 	}
 }