Add --exclude-tools (and X-MCP-Exclude-Tools) flag to enable shutting off tools as part of server configuration

[tommaso-moro]

Closes https://github.com/github/copilot-mcp-core/issues/1292

Update: --disallow-tools and X-MCP-Disallow-Tools have been renamed to --exclude-tools and X-MCP-Exclude-Tools

Summary

Adds support for excluding tools: a new way to disable specific tools regardless of any other configuration. This is the inverse of --tools, which is used to enable specific tools. Tools listed in exclude-tools are always removed, even if their toolset is enabled or they are explicitly added via --tools / X-MCP-Tools.

Local server:

• --exclude-tools=create_issue,push_files flag
• GITHUB_EXCLUDE_TOOLS env var

Remote server (after bumping this dependency):

• I have a PR to add X-MCP-Exclude-Tools header to the remote server, and will merge it once this PR has been merged and shipped with the next release : https://github.com/github/github-mcp-server-remote/pull/705

Demo

Stdio mode:
https://github.com/user-attachments/assets/3e8e866f-3fc8-4c03-8258-ed2293cc07c2

Using http mode:

Motivation

This enables configs like:

{
  "--toolsets": "pull_requests",
  "--exclude-tools": "create_pull_request,merge_pull_request"
}

And in general it allows for better security + easier server configuration.

What changed

New CLI flag and env var

• --exclude-tools flag (comma-separated list of tool names to disable)
• GITHUB_EXCLUDE_TOOLS env var (equivalent)

New inventory builder APIs

• Builder.WithDisallowedTools([]string): builder method that adds a filter to exclude the named tools. Input is cleaned (trimmed, deduplicated). No-op if the list is empty or nil.
• inventory.CreateDisallowedToolsFilter([]string): exported standalone filter constructor. Returns a ToolFilter that excludes tools by name. Exported so the remote server can use it directly if preferred.

Both are thin wrappers around the existing WithFilter mechanism: disallowed tools are implemented as a builder filter (step 4 in filter evaluation), which runs before the toolset/additional-tools check (step 5). This means a tool present in both --tools and --disallowed-tools will be disallowed.

HTTP entrypoint support

In addition to the --disallowed-tools CLI flag for stdio mode, this PR adds full support for the X-MCP-Disallowed-Tools HTTP header in the HTTP entrypoint (github-mcp-server http). This ensures the feature works across both transport modes and is available to the remote server (github-mcp-server-remote) which imports this repo's pkg/http package.

File	Description
pkg/http/headers/headers.go	MCPDisallowedToolsHeader = "X-MCP-Disallowed-Tools" constant
pkg/context/request.go	WithDisallowedTools() / GetDisallowedTools() context helpers
pkg/http/middleware/request_config.go	Parses X-MCP-Disallowed-Tools header into request context
pkg/http/handler.go	InventoryFiltersForRequest applies WithDisallowedTools() from context
pkg/http/handler_test.go	8 new test cases covering header parsing, toolset interaction, explicit tools override, and readonly composition

I added tests too and updated the docs.

MCP impact

• No tool or API changes
• Tool schema or behavior changed
• New tool added

Prompts tested (tool changes only)

Security / limits

• No security or limits impact
• Auth / permissions considered
• Data exposure, filtering, or token/size limits considered

Tool renaming

• I am renaming tools as part of this PR (e.g. a part of a consolidation effort)
  • I have added the new tool aliases in deprecated_tool_aliases.go
• I am not renaming tools as part of this PR

Note: if you're renaming tools, you must add the tool aliases. For more information on how to do so, please refer to the official docs.

Lint & tests

• Linted locally with ./script/lint
• Tested locally with ./script/test

Docs

• Not needed
• Updated (README / docs / examples)

[Copilot]

Pull request overview

This PR adds support for disallowed tools - a new way to disable specific tools regardless of any other configuration settings. This feature allows administrators to blocklist specific tools for security, compliance, or operational reasons. The implementation adds a --disallowed-tools flag for the local stdio server and documents (but does not implement) the corresponding X-MCP-Disallowed-Tools header for the remote server.

Changes:

• Added WithDisallowedTools() builder method and CreateDisallowedToolsFilter() to the inventory package for filtering out specific tools by name
• Added CLI flag --disallowed-tools and environment variable GITHUB_DISALLOWED_TOOLS support for the local stdio server
• Added comprehensive test coverage including edge cases and interaction with read-only mode and additional tools
• Updated documentation in docs/server-configuration.md to describe the feature and provide examples

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
pkg/inventory/builder.go	Added WithDisallowedTools() method and CreateDisallowedToolsFilter() function to enable tool blocklisting via builder filters
pkg/inventory/registry_test.go	Added comprehensive test coverage for disallowed tools functionality including edge cases and interaction tests
pkg/github/server.go	Added DisallowedTools field to MCPServerConfig struct
internal/ghmcp/server.go	Added DisallowedTools field to StdioServerConfig and wired it through to MCPServerConfig
cmd/github-mcp-server/main.go	Added --disallowed-tools CLI flag, environment variable binding, and parsing logic
docs/server-configuration.md	Added documentation section and examples for disallowed tools feature, including both local and remote server usage

[IrynaKulakova]

hey @tommaso-moro, what would be user experience if we have the same tool explicitly enabled and disallowed ?

[tommaso-moro]

@IrynaKulakova disallow always takes priority, so the tool would not be enabled if it's in the "disallowed-tools" list, regardless of other configurations:)

[tommaso-moro]

Update
Based on @SamMorrowDrums 's suggestion, I have renamed the flag from --disallowed-tools and X-MCP-Disallowed-Tools to --exclude-tools and X-MCP-Exclude-Tools