Add docs for Insiders Mode (#2095)

* update docs

* add mention of new doc

* Update docs/insiders-features.md

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

---------

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

Author: tommaso-moro

README.md

@@ -140,7 +140,7 @@ When no toolsets are specified, [default toolsets](#default-toolset) are used.
 </tr>
 </table>
 
-See [Remote Server Documentation](docs/remote-server.md#insiders-mode) for more details and examples.
+See [Remote Server Documentation](docs/remote-server.md#insiders-mode) for more details and examples, and [Insiders Features](docs/insiders-features.md) for a full list of what's available.
 
 #### GitHub Enterprise
 

docs/insiders-features.md

@@ -0,0 +1,44 @@
+# Insiders Features
+
+Insiders Mode gives you access to experimental features in the GitHub MCP Server. These features may change, evolve, or be removed based on community feedback.
+
+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! 
+
+> [!NOTE]
+> Features in Insiders Mode are experimental.
+
+## Enabling Insiders Mode
+
+| Method | Remote Server | Local Server |
+|--------|---------------|--------------|
+| URL path | Append `/insiders` to the URL | N/A |
+| Header | `X-MCP-Insiders: true` | N/A |
+| CLI flag | N/A | `--insiders` |
+| Environment variable | N/A | `GITHUB_INSIDERS=true` |
+
+For configuration examples, see the [Server Configuration Guide](./server-configuration.md#insiders-mode).
+
+---
+
+## 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

docs/server-configuration.md

@@ -13,6 +13,7 @@ We currently support the following ways in which the GitHub MCP Server can be co
 | Read-Only Mode | `X-MCP-Readonly` header or `/readonly` URL | `--read-only` flag or `GITHUB_READ_ONLY` env var |
 | 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 |
 | Scope Filtering | Always enabled | Always enabled |
 
 > **Default behavior:** If you don't specify any configuration, the server uses the **default toolsets**: `context`, `issues`, `pull_requests`, `repos`, `users`.
@@ -384,6 +385,63 @@ Lockdown mode ensures the server only surfaces content in public repositories fr
 
 ---
 
+### Insiders Mode
+
+**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. 
+
+<table>
+<tr><th>Remote Server</th><th>Local Server</th></tr>
+<tr valign="top">
+<td>
+
+**Option A: URL path**
+```json
+{
+  "type": "http",
+  "url": "https://api.githubcopilot.com/mcp/insiders"
+}
+```
+
+**Option B: Header**
+```json
+{
+  "type": "http",
+  "url": "https://api.githubcopilot.com/mcp/",
+  "headers": {
+    "X-MCP-Insiders": "true"
+  }
+}
+```
+
+</td>
+<td>
+
+```json
+{
+  "type": "stdio",
+  "command": "go",
+  "args": [
+    "run",
+    "./cmd/github-mcp-server",
+    "stdio",
+    "--insiders"
+  ],
+  "env": {
+    "GITHUB_PERSONAL_ACCESS_TOKEN": "${input:github_token}"
+  }
+}
+```
+
+</td>
+</tr>
+</table>
+
+See [Insiders Features](./insiders-features.md) for a full list of what's available in Insiders Mode.
+
+---
+
 ### Scope Filtering
 
 **Automatic feature:** The server handles OAuth scopes differently depending on authentication type: