Feature: Declarative Tool Filtering in MCP Server Configuration

[coygeek]

Title: Feature: Declarative Tool Filtering in MCP Server Configuration

Labels: enhancement, mcp, configuration, security

Body

Is your feature request related to a problem? Please describe.

Currently, when an MCP server is configured in claude-code (e.g., via .mcp.json), all tools exposed by that server are discovered by the model by default. The only way to control which of these tools can be used is after discovery, via the separate permissions system (/permissions, .claude/settings.json, or the --allowedTools/--disallowedTools flags).

This "all-or-nothing" discovery approach presents a few significant challenges:

• Security Risk (Least Privilege Violation): Unnecessary or potentially sensitive tools are exposed to the model's context, even if they are ultimately denied by the permissions system. This increases the attack surface for potential prompt injection or misuse and violates the principle of least privilege at the tool discovery layer.
• Configuration Clutter: For a server with many tools, the central .claude/settings.json permissions list becomes cluttered with many allow and deny rules specific to that single server. This makes the configuration harder to manage, audit, and understand at a glance.
• Lack of Declarative Control: The server definition in .mcp.json is completely decoupled from its intended toolset. It's not possible to look at the server's configuration and immediately understand which subset of its tools are meant to be active for the project.

Describe the solution you'd like

I propose enhancing the MCP server configuration schema to include optional tool-filtering fields. This would allow for declarative, upfront control over which tools are ever loaded from a given server, co-locating the tool manifest with the server definition itself.

The new fields in the server configuration object would be:

• includeTools: string[] (optional) - A whitelist of tool names to load from the server. If this array is present, only tools with names in this list will be discovered by claude-code.
• excludeTools: string[] (optional) - A blacklist of tool names to not load from the server. All tools will be discovered except those in this list.

Precedence & Behavior Rules:

1. Exclusion Over Inclusion: If both includeTools and excludeTools are defined for the same server, excludeTools takes precedence. A tool present in both lists will be excluded.
2. Default Behavior: If neither field is defined, the current behavior (discover all tools) is maintained for backward compatibility.
3. Complements Existing Permissions: The standard permissions system (/permissions, settings.json, etc.) would still apply to the final, filtered set of discovered tools, providing a second layer of defense and runtime control.

Examples

Imagine an MCP server named github that exposes list_issues, create_issue, and a sensitive delete_repo tool.

Current Workflow (Problematic):

The configuration is split across two files, and the model is made aware of the dangerous delete_repo tool.

.mcp.json:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    }
  }
}

.claude/settings.json:

{
  "permissions": {
    "allow": [
      "mcp__github__list_issues",
      "mcp__github__create_issue"
    ],
    "deny": [
      "mcp__github__delete_repo"
    ]
  }
}

Proposed Workflow (Solution):

The configuration is declarative, co-located, and more secure. The model is never even aware of the delete_repo tool.

Option A: Whitelisting with includeTools (Recommended for security)

.mcp.json:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "includeTools": [
        "list_issues",
        "create_issue"
      ]
    }
  }
}

(No corresponding deny rule is needed in settings.json for basic filtering, as the dangerous tool is never loaded).

Option B: Blacklisting with excludeTools

.mcp.json:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "excludeTools": [
        "delete_repo"
      ]
    }
  }
}

What are the benefits of this feature?

• Improved Security: Implements the principle of least privilege at the tool discovery layer. The model is never made aware of tools it shouldn't use, reducing the overall attack surface.
• Simplified & Co-located Configuration: Reduces the need for long, complex allow/deny lists in the central settings.json, making permissions easier to manage.
• Self-Documenting & Auditable: The .mcp.json file becomes a clear, declarative manifest of which server tools are active for a project, improving readability, maintainability, and auditability for security teams.
• Proactive Safety: When a third-party MCP server adds a new, potentially dangerous tool in an update, it won't be automatically exposed to the model if a project is using an includeTools whitelist.

Describe alternatives you've considered

The only alternative is the current system of using the global permissions list. As detailed above, this works for runtime authorization but is insufficient for controlling tool discovery, leading to the security and configuration management drawbacks mentioned. This proposal complements the existing permissions system by adding a critical, declarative layer of control at the source.

[github-actions[bot]]

Found 3 possible duplicate issues:

1. https://github.com/anthropics/claude-code/issues/1424
2. https://github.com/anthropics/claude-code/issues/82
3. https://github.com/anthropics/claude-code/issues/4380

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

[gabrielbryk]

Please bump this. I only have serena, zen, and context7 installed at it eats up 20% of my context alone. I know I can disable some of the tools but I don't want to have to constantly be playing around with those settings depending on my task

[AuthenTech-AI]

I just submitted a similar request and saw it as a duplicate of your request. I love your solution and would love to see it implemented.

[PaulRBerg]

It's time to add support for this feature in Claude Code. Gemini already offers includeTools and excludeTools settings.

One important downside of not being able to exclude tools is context size. 27% of my context is gobbled up by the user-level MCP tools:

Related: https://github.com/orgs/modelcontextprotocol/discussions/559

[StupidIncarnate]

I would love even more control to trim off that and some of the stuff in system tools. Im assuming the github stuff is bundled in there and its quite useless for usage at work where we use gitlab.

[github-actions[bot]]

This issue has been inactive for 30 days. If the issue is still occurring, please comment to let us know. Otherwise, this issue will be automatically closed in 30 days for housekeeping purposes.

[eXamadeus]

I really like the idea of removing certain tools from servers at the definition. This is super useful for security purposes.

For context management, I think this is only a partial solution. There are a few other issues, I provide a little summary here, that want to address the scoping of tools and context pollution. Overall the context management for MCP is abysmal. I added this as a "somewhat related issue" in an attempt to clarify the state of our requests. I don't think Anthropic will notice unless there is a very clear "definition" of our requests.

Ideally I would like to be able to:

• exclude dangerous tools from the tool definition (this issue)
• scope which tools my main agent has access to WITHOUT context pollution
• scope which tools my sub agents have access to WITHOUT context pollution

I think we all basically want these things, but they're scattered across multiple issues with no clarifying push forward.