RFC - Prototype for MCP Tool Filtering

The problem outlined below is not unique to the GitHub MCP Server; but this server has a lot of tools that are well understood by the community (and there's many more to implement!) so this felt like an ideal place for prototyping.

Problem

MCP Servers conventionally expose all tools they are capable of; which clients discover via tools/list. There are a number of problems with this:

• A user may wish to prevent their agents from using specific tools, while making use of other parts of the MCP Server.
  • Example: Some tools may be considered high risk
  • Example: Some tools may be capable of returning data which is not allowed to be exposed to LLMs
• Some clients have limitations on the number of MCP Servers and Tools they can interact with
  • Example: Cursor limits users to interacting with the first 40 tools discovered across servers
• Exposing unnecessary tools to agents is a waste of tokens
• Exposing undesired tools to agents pollutes context and confuses agents by giving a false sense of agency
• Some tools may not be available to the user because the credentials they associated with the server lack permission for the backing APIs

Additionally, there are use cases in which a user may wish to have multiple instances of the same MCP Server, with differing configurations and tools available.

• Example:
  • Instance A of Github MCP, using an access token for Organization A, only accessing tools to read Pull Requests
  • Instance B of Github MCP, using an access token for Organization B, only accessing Issues and Users

Proposal

Standardize --include-tools and --exclude-tools arguments when invoking stdio transport CLI tools.

• --include-tools applies an allowlist approach; only exposing the tools specified by the user
• --exclude-tools applies a denylist approach; exposing all tools except those specified by the user

By providing these as arguments to the process itself, we ensure the server itself does not register these tools.

• This prevents them from being exposed to tools/list
• This prevents agents from calling them
• This ensures agents don't waste context tokens to know about tools they can't use

Example Usage

In this branch, I have hacked filtering into the GitHub MCP Server. In Cursor's MCP configuration, I specify two instances of this server, with different tools available:

  "mcpServers": {
    "github-mc-local-with-includes": {
      "command": "./github-mcp-server",
      "args": [
        "stdio",
        "--include-tools",
        "update_issue,create_issue"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "OH_HI_THERE"
      }
    },
    "github-mc-local-with-excludes": {
      "command": "./github-mcp-server",
      "args": [
        "stdio",
        "--exclude-tools",
        "get_file_contents,get_issue,get_issue_comments,get_me,get_pull_request,get_pull_request_comments,get_pull_request_files,get_pull_request_reviews,get_pull_request_status,list_code_scanning_alerts,list_commits,list_issues,list_pull_requests"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "LOL_NO_THANKS"
      }
    }
  }

Thus Cursor shows the filtered tools which are available:

Pros

• Works with docker-based local MCP Servers
• Works with local binaries
• Works with NPM, NPX, etc. based local MCP servers
• Allows users to store, share, and version control tool filters in the same place they store their server configurations (eg. mcp.json)
• Filters entirely upstream of agents and human-in-the-loop tool approvals
• Filtering at this level allows for server-specific groups of filters as well (eg. --read-only or --exclude-super-admin-tools)
• This would also allow servers to make dynamic decisions about tools to expose.
  • Example: On server process initialization, make an API call to inspect permissions associated with the client's credentials. Only expose tools which they have permission to use.

Cons

• SSE Transport.... 🤔

Alternatives

• Do nothing - Leave this as an entirely client-side concern (Claude, Cursor, etc improve their UX around which tools should be available)