How to Configure Toolset Filtering for Specific GitHub API Capabilities in GitHub MCP Server

Configure toolset filtering by using the --toolsets CLI flag, GITHUB_TOOLSETS environment variable, or X-MCP-Toolsets HTTP header to limit which GitHub API capabilities are exposed, while OAuth scope filtering automatically restricts tools based on your token's permissions.

The GitHub MCP Server organizes GitHub API operations into logical toolsets like repos, issues, and pull_requests. When you configure toolset filtering for specific GitHub API capabilities, you control exactly which operations are available to MCP clients, improving security and reducing token scope requirements.

Understanding Toolset Architecture

The server groups related GitHub API operations into toolsets defined in pkg/github/tools.go. Each toolset contains metadata including an ID, description, default status, and icon.

Toolset Metadata Definitions

Toolset metadata is declared using inventory.ToolsetMetadata structs. For example, the repos toolset is defined in pkg/github/tools.go as:

ToolsetMetadataRepos = inventory.ToolsetMetadata{
    ID:          "repos",
    Description: "GitHub Repository related tools",
    Default:     true,
    Icon:        "repo",
}

These metadata entries drive both the filtering logic and documentation generation.

OAuth Scope Filtering

For classic personal access tokens (ghp_…), the server automatically filters tools based on the token's OAuth scopes. The server reads the X-OAuth-Scopes header and hides any tool whose required scopes are not present.

This scope filtering is always active for classic PATs and takes precedence over explicit toolset selection. If a token lacks a required scope, the corresponding tool remains hidden regardless of your --toolsets configuration.

Configuration Methods for Toolset Filtering

You can configure toolset filtering through multiple interfaces depending on your deployment model.

CLI Flags

When running the local server executable, use the --toolsets flag to specify a comma-separated list of toolset IDs:

github-mcp-server stdio \
  --toolsets=issues,pull_requests \
  --read-only=false

Passing --toolsets= (empty value) disables all toolsets, useful when enabling dynamic toolset loading.

Environment Variables

Set the GITHUB_TOOLSETS environment variable to configure toolsets without modifying command-line arguments:

export GITHUB_TOOLSETS="issues,repos"
github-mcp-server stdio

HTTP Headers for Remote Servers

When connecting to the remote server at api.githubcopilot.com, pass the X-MCP-Toolsets header:

{
  "type": "http",
  "url": "https://api.githubcopilot.com/mcp/",
  "headers": {
    "X-MCP-Toolsets": "repos",
    "Authorization": "Bearer <classic-PAT>"
  }
}

URL Path Routing

Remote servers also support path-based toolset selection:

• …/x/issues – enables only the issues toolset
• …/x/repos – enables only the repos toolset

Builder API and Programmatic Configuration

For Go applications embedding the GitHub MCP Server, the builder API in pkg/inventory/builder.go provides fine-grained control.

Using WithToolsets and WithTools

The WithToolsets method (lines 99-112 in pkg/inventory/builder.go) records desired toolset IDs:

reg := githubmcp.NewBuilder().
    SetTools(allTools).
    WithToolsets([]string{"issues"}).   // only issue-related tools
    WithTools([]string{"get_me"}).      // add cross-toolset utility
    Build()

Tools added via WithTools bypass toolset filtering but still respect read-only mode restrictions.

ProcessToolsets Implementation Details

The processToolsets function (lines 46-106 in pkg/inventory/builder.go) handles:

• Keyword expansion: Converts all to every available toolset, default to toolsets marked with Default: true
• Validation: Returns errors for unrecognized toolset IDs
• Deduplication: Removes duplicate entries while preserving order
• Empty handling: Interprets empty input as "no toolsets" when dynamic loading is enabled

During Build(), the server collects tools and their metadata from pkg/github/tools.go, applies processToolsets() to compute the enabled set, and constructs an Inventory that the HTTP handler uses to expose tools.

Scope Filtering and Read-Only Mode

Two additional filtering layers affect tool availability regardless of toolset selection.

OAuth Scope Filtering automatically hides tools requiring scopes your token lacks. For example, if your PAT has repo but not admin:org, organization administration tools remain hidden even when explicitly requested via --toolsets.

Read-Only Mode (--read-only flag or X-MCP-Readonly header) removes all write-capable tools from the inventory. This supersedes both scope filtering and toolset selection, ensuring no mutation operations are exposed even if the token permissions would allow them.

Practical Examples

Enable Specific Toolsets via CLI

Run the server with only repository and issue tools available:

go run ./cmd/github-mcp-server stdio \
  --toolsets=repos,issues \
  --read-only=false \
  --dynamic-toolsets=false

This exposes all tools in the repos and issues toolsets while hiding pull_requests, code_scanning, and others.

Remote Client Configuration

Configure a remote MCP client to access only repository information:

{
  "type": "http",
  "url": "https://api.githubcopilot.com/mcp/",
  "headers": {
    "X-MCP-Toolsets": "repos",
    "Authorization": "Bearer ghp_xxxxxxxxxxxx"
  }
}

If the provided PAT only has public_repo scope, the server automatically filters out private repository operations regardless of the header configuration.

Combining Toolsets with Explicit Tools

Use the Go builder API to enable the issues toolset plus a specific user tool:

reg := githubmcp.NewBuilder().
    SetTools(allTools).
    WithToolsets([]string{"issues"}).   // only issue-related tools
    WithTools([]string{"get_me"}).      // add a cross-toolset utility
    Build()

The get_me tool bypasses the issues filter but remains subject to read-only mode restrictions.

Disabling All Toolsets for Dynamic Loading

Start the server with no initial toolsets to enable dynamic discovery:

go run ./cmd/github-mcp-server stdio \
  --toolsets= \
  --dynamic-toolsets=true

The empty --toolsets= value tells processToolsets to start with an empty enabled set, allowing tools to be loaded on demand via the dynamic discovery protocol.

Summary

• Toolset filtering in the GitHub MCP Server controls which GitHub API capabilities are exposed to clients through logical groupings like repos, issues, and pull_requests.
• Configuration options include the --toolsets CLI flag, GITHUB_TOOLSETS environment variable, and X-MCP-Toolsets HTTP header for remote deployments.
• Builder API methods WithToolsets and WithTools in pkg/inventory/builder.go provide programmatic control, with processToolsets handling keyword expansion (all, default) and validation.
• Automatic filtering occurs through OAuth scope detection for classic PATs, hiding tools requiring scopes your token lacks regardless of explicit toolset selection.
• Read-only mode supersedes all other filters, removing write-capable tools even when tokens and toolsets would otherwise permit them.

Frequently Asked Questions

How do I enable only the repositories toolset when starting the server?

Pass the --toolsets flag with the repos value when executing the server binary. For example: github-mcp-server stdio --toolsets=repos. This exposes only repository-related tools while hiding issues, pull requests, and other capabilities.

Why are some tools hidden even when I explicitly include their toolset in the configuration?

When using classic personal access tokens (PATs), the server automatically filters tools based on your token's OAuth scopes. If your token lacks a required scope (such as admin:org or write:discussion), tools requiring that scope remain hidden regardless of your --toolsets selection. Use a token with broader scopes or switch to fine-grained tokens which bypass this check.

What is the difference between --toolsets=all and --toolsets=default?

The all keyword expands to every available toolset defined in pkg/github/tools.go, while default includes only toolsets marked with Default: true in their metadata (such as repos, issues, and pull_requests). Use all when you need comprehensive API access, or default for a curated subset of common operations.

How does read-only mode interact with toolset filtering?

Read-only mode (--read-only or X-MCP-Readonly header) takes precedence over both toolset selection and OAuth scope filtering. When enabled, the server removes all write-capable tools from the inventory before exposing them to the client, ensuring no mutation operations are available even if your token permissions and toolset configuration would otherwise allow them.

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