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

> Learn to configure toolset filtering for GitHub API capabilities in GitHub MCP Server using CLI flags environment variables or HTTP headers to precisely control exposed API access.

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

---

**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`](https://github.com/github/github-mcp-server/blob/main/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`](https://github.com/github/github-mcp-server/blob/main/pkg/github/tools.go) as:

```go
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:

```bash
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:

```bash
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:

```json
{
  "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`](https://github.com/github/github-mcp-server/blob/main/pkg/inventory/builder.go) provides fine-grained control.

### Using WithToolsets and WithTools

The `WithToolsets` method (lines 99-112 in [`pkg/inventory/builder.go`](https://github.com/github/github-mcp-server/blob/main/pkg/inventory/builder.go)) records desired toolset IDs:

```go
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`](https://github.com/github/github-mcp-server/blob/main/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`](https://github.com/github/github-mcp-server/blob/main/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:

```bash
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:

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

```go
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:

```bash
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`](https://github.com/github/github-mcp-server/blob/main/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`](https://github.com/github/github-mcp-server/blob/main/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.