GitHub MCP Server Insiders Mode: Experimental Features Explained

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, 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:

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

Alternatively, append /insiders to the base URL:

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

These options are documented in docs/remote-server.md and handled by the middleware in pkg/http/handler.go.

Local Server Configuration

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

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

Or set the environment variable before starting the server:

export GITHUB_INSIDERS=true
github-mcp-server stdio

The flag parsing logic resides in 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 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.

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 and pkg/github/issues.go, the code checks:

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, 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:

{
  "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:

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:

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 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 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 and related handler files.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}