# GitHub MCP Server Insiders Mode: Experimental Features Explained

> Explore GitHub MCP server insiders mode experimental features like UI metadata payloads and restricted tools. Unlock advanced capabilities by enabling this mode.

- Repository: [GitHub/github-mcp-server](https://github.com/github/github-mcp-server)
- Tags: deep-dive
- Published: 2026-02-16

---

**Insiders mode unlocks experimental capabilities in the GitHub MCP server—including UI metadata payloads and restricted tools—by setting a configuration flag, HTTP header, or URL path suffix.**

The `github/github-mcp-server` repository provides a Model Context Protocol (MCP) server that exposes GitHub functionality to AI assistants. When you enable **experimental features MCP server insiders mode**, you gain access to bleeding-edge tooling that is gated behind explicit safety checks to prevent accidental production use.

## What Is MCP Server Insiders Mode?

Insiders mode is a runtime toggle that distinguishes between stable, production-ready features and experimental functionality still under development. When activated, the server bypasses sanitization routines that normally strip experimental metadata and disable preview tools.

According to the source code in [`pkg/inventory/builder.go`](https://github.com/github/github-mcp-server/blob/main/pkg/inventory/builder.go), the mode controls three primary gates: the preservation of UI metadata keys, the inclusion of `InsidersOnly` tools, and the activation of feature-flag-driven UI flows.

## How to Enable Insiders Mode

You can activate insiders mode through multiple interfaces depending on whether you are running a remote or local instance.

### Remote Server Configuration

For remote deployments, pass the flag via an HTTP header or URL path suffix.

Add the header to your MCP client configuration:

```json
{
  "type": "http",
  "url": "https://api.githubcopilot.com/mcp",
  "headers": {
    "X-MCP-Insiders": "true"
  }
}

```

Alternatively, append `/insiders` to the base URL:

```json
{
  "type": "http",
  "url": "https://api.githubcopilot.com/mcp/insiders"
}

```

These options are documented in [`docs/remote-server.md`](https://github.com/github/github-mcp-server/blob/main/docs/remote-server.md) and handled by the middleware in [`pkg/http/handler.go`](https://github.com/github/github-mcp-server/blob/main/pkg/http/handler.go).

### Local Server Configuration

When running the binary locally, use the `--insiders` CLI flag:

```bash
github-mcp-server stdio --insiders \
  --tools=get_me,get_file_contents \
  --toolsets=issues,pull_requests

```

Or set the environment variable before starting the server:

```bash
export GITHUB_INSIDERS=true
github-mcp-server stdio

```

The flag parsing logic resides in [`cmd/github-mcp-server/main.go`](https://github.com/github/github-mcp-server/blob/main/cmd/github-mcp-server/main.go) and propagates to `inventory.NewBuilder().WithInsidersMode()`.

## Experimental Features Available in Insiders Mode

Enabling insiders mode unlocks three categories of experimental functionality.

### UI Metadata for MCP Apps (`ui` key)

The server can expose a special `ui` metadata key within a tool’s definition that describes how a client should render a user interface for that tool. When insiders mode is **disabled**, the function `stripInsidersMetaFromTool` in [`pkg/inventory/builder.go`](https://github.com/github/github-mcp-server/blob/main/pkg/inventory/builder.go) removes this key from every tool’s `Meta` map.

When insiders mode is **enabled**, the `ui` payload is preserved, allowing clients to display rich interfaces for tools like pull request creation.

### Insiders-Only Tools

Developers can mark specific tools as experimental by setting the `InsidersOnly` boolean field on the `ServerTool` struct defined in [`pkg/inventory/server_tool.go`](https://github.com/github/github-mcp-server/blob/main/pkg/inventory/server_tool.go).

During inventory construction, the `stripInsidersFeatures` function filters out any tool where `InsidersOnly` is true unless the builder has `insidersMode` set to true. This allows the maintainers to ship preview tools without exposing them to stable production users.

### Feature-Flag-Driven UI Gates

Certain GitHub-specific workflows, such as rendering a web UI for issue or pull request creation, are guarded by runtime feature flag checks. In [`pkg/github/pullrequests.go`](https://github.com/github/github-mcp-server/blob/main/pkg/github/pullrequests.go) and [`pkg/github/issues.go`](https://github.com/github/github-mcp-server/blob/main/pkg/github/issues.go), the code checks:

```go
deps.GetFlags(ctx).InsidersMode && clientSupportsUI(req)

```

Both conditions must be true for the experimental UI flow to execute. This ensures that even if insiders mode is enabled server-side, the client must also advertise UI support before triggering experimental interface paths.

## Architecture and Implementation Details

The insiders mode implementation follows a builder pattern that sanitizes the tool inventory before it reaches the MCP client.

In [`pkg/inventory/builder.go`](https://github.com/github/github-mcp-server/blob/main/pkg/inventory/builder.go), the `Builder` struct maintains an `insidersMode` boolean. When `Build()` is invoked:

1. If `insidersMode` is false, `stripInsidersFeatures` iterates over the tool list and drops any `ServerTool` with `InsidersOnly: true`.
2. It then calls `stripInsidersMetaFromTool` on remaining tools, which deletes keys matching the `insidersOnlyMetaKeys` slice (currently containing only `"ui"`).

The resulting `Inventory` object contains only production-safe tools and metadata. When `insidersMode` is true, these stripping functions are skipped, exposing the full experimental surface.

## Code Examples

### Enable Insiders Mode via JSON Configuration

Configure your MCP client to connect to the insiders endpoint:

```json
{
  "type": "http",
  "url": "https://api.githubcopilot.com/mcp/insiders",
  "headers": {
    "Authorization": "Bearer ${GITHUB_TOKEN}"
  }
}

```

### Programmatically Build an Inventory with Insiders Mode

When embedding the server in your own Go application:

```go
import "github.com/github/github-mcp-server/pkg/inventory"

func main() {
    builder := inventory.NewBuilder().
        SetTools(allTools).
        WithToolsets([]string{"all"}).
        WithInsidersMode(true)  // Enable experimental features
    
    inv, err := builder.Build()
    if err != nil {
        log.Fatal(err)
    }
    // Use inv...
}

```

### Define an Insiders-Only Tool

Mark a tool as experimental in your tool definition:

```go
var experimentalTool = inventory.ServerTool{
    Tool: mcp.Tool{
        Name:        "preview_feature",
        Description: "Experimental preview functionality",
    },
    InsidersOnly: true,  // Gated by insiders mode
    HandlerFunc: func(deps any) mcp.ToolHandler {
        return func(ctx context.Context, req *mcp.CallToolRequest) (*mcp.CallToolResult, error) {
            // Implementation here
            return &mcp.CallToolResult{}, nil
        }
    },
}

```

## Summary

- **Insiders mode** unlocks experimental capabilities in the GitHub MCP server that are hidden from standard production builds.
- **Enable it** via the `--insiders` CLI flag, `GITHUB_INSIDERS=true` environment variable, `X-MCP-Insiders: true` HTTP header, or `/insiders` URL suffix.
- **Experimental features** include the `ui` metadata key for rich client interfaces, tools marked `InsidersOnly`, and feature-flag-gated UI workflows in issues and pull requests.
- **Implementation** relies on the `inventory.Builder` in [`pkg/inventory/builder.go`](https://github.com/github/github-mcp-server/blob/main/pkg/inventory/builder.go) to strip experimental tools and metadata when the mode is disabled.

## Frequently Asked Questions

### How do I know if insiders mode is active on my server?

Check the server logs or inspect the tool inventory returned by the server. If the `ui` metadata key is present in tool definitions or if tools marked as `InsidersOnly` appear in the list, insiders mode is enabled. You can also verify by checking if the `X-MCP-Insiders` header was accepted or if the `/insiders` path was used.

### Can I use insiders mode in production environments?

While technically possible, insiders mode is designed for **testing and development** of experimental features. The `ui` metadata and insiders-only tools may change without notice, break compatibility, or expose unstable functionality. Production deployments should use the default stable mode unless specifically requiring a vetted experimental capability.

### What happens to UI metadata when insiders mode is disabled?

When insiders mode is disabled, the `stripInsidersMetaFromTool` function in [`pkg/inventory/builder.go`](https://github.com/github/github-mcp-server/blob/main/pkg/inventory/builder.go) automatically removes the `ui` key from every tool's metadata map before the inventory is served to clients. This ensures that production clients never receive experimental UI hints or rendering instructions intended only for insiders builds.

### Are insiders-only tools documented in the standard schema?

No. Tools with `InsidersOnly: true` are filtered out of the inventory entirely when insiders mode is disabled, so they do not appear in the standard tool schema or discovery endpoints. Documentation for these tools typically resides in internal READMEs, the `docs/` directory, or inline code comments within [`pkg/inventory/server_tool.go`](https://github.com/github/github-mcp-server/blob/main/pkg/inventory/server_tool.go) and related handler files.