Configure Tools Filtering In MCP With EnabledTools/disabledTools

by Alex Johnson 65 views

In the realm of MCP (Meta-Config Protocol) servers, managing a plethora of tools can sometimes feel like navigating a dense forest. When an MCP server exposes a multitude of tools, the ability to selectively filter and load specific tools becomes not just a convenience, but a necessity. This is where the enabledTools and disabledTools configurations come into play, offering a powerful mechanism to streamline your workflow and optimize resource utilization. This article delves into the intricacies of configuring enabledTools and disabledTools in mcp.json, providing a comprehensive guide to per-tool filtering.

Understanding the Problem: Context Bloat and the Need for Filtering

When working with MCP servers that offer a wide array of tools, the challenge of context bloat quickly surfaces. Context bloat refers to the unnecessary consumption of resources, particularly tokens, by tool definitions that are not actively in use. Imagine a scenario where you only require a handful of tools from a server that exposes dozens. Without a filtering mechanism, all tool definitions are loaded into the context, consuming tokens and potentially impacting performance. This not only wastes valuable resources but also clutters the available tools list, making it harder to find and utilize the tools you actually need.

The existing methods for managing tools in MCP servers often fall short of providing a persistent and efficient solution. Disabling the entire server ("disabled": true) is a drastic measure that cuts off access to all tools, even the ones you might need. Using command-line interface (CLI) flags (--disabled-tools / --enabled-tools) offers a more granular approach, but it's not persistent. You have to specify the flags every time you invoke the server, which can become tedious and error-prone. This lack of persistent configuration necessitates a more robust solution for tool filtering.

Introducing the Solution: enabledTools and disabledTools

To address the challenges of context bloat and the need for persistent tool filtering, the introduction of enabledTools and disabledTools arrays in the MCP server configuration schema is a game-changer. These arrays, configurable within the ~/.factory/mcp.json and .factory/mcp.json files, provide a flexible and persistent way to control which tools are loaded into context.

The configuration structure is straightforward and intuitive. Within the mcpServers section of your mcp.json file, you can define servers and their properties. The enabledTools and disabledTools arrays are added as properties within each server's configuration. Let's take a look at an example:

{
  "mcpServers": {
    "my-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@some/mcp-server"],
      "disabled": false,
      "disabledTools": ["tool_i_dont_need", "another_unused_tool"]
    },
    "another-server": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "enabledTools": ["only_tool_i_want", "and_this_one"]
    }
  }
}

In this example, my-server is configured to exclude tool_i_dont_need and another_unused_tool from being loaded, while another-server is configured to only load only_tool_i_want and and_this_one. This level of granularity ensures that only the necessary tools are loaded, optimizing resource utilization and reducing context bloat.

Understanding the Behavior of enabledTools and disabledTools

It's crucial to understand the behavior of enabledTools and disabledTools to effectively utilize them. Here's a breakdown:

  • disabledTools: This array implements a blocklist approach. It specifies the tools that should be excluded from being loaded. If a tool is listed in disabledTools, it will not be loaded into the context.
  • enabledTools: This array implements an allowlist approach. It specifies the only tools that should be loaded. If a tool is not listed in enabledTools, it will not be loaded into the context.
  • Precedence: When both enabledTools and disabledTools are specified, enabledTools takes precedence. This means that only the tools listed in enabledTools will be loaded, regardless of what's in disabledTools. Alternatively, the configuration may throw an error to prevent ambiguity. This behavior ensures clarity and prevents unintended consequences.
  • Impact on Context: The most significant aspect of these configurations is that disabled tools are not loaded into context at all. This is a crucial distinction from simply blocking tools from execution. By preventing the tools from being loaded, you directly reduce the context size and minimize resource consumption.

Real-World Use Cases: Streamlining Your Workflow

The practical benefits of enabledTools and disabledTools are best illustrated through real-world use cases. Imagine you're working with an MCP server that provides a vast suite of tools, but your current project only requires a specific subset. Without tool filtering, you'd be forced to load all the tools, consuming unnecessary resources and cluttering your workspace.

Consider a scenario where you use an MCP server that publishes many tools, but you only need tool1 and tool2. Previously, you might have had to:

  1. Accept all tools, leading to context token consumption.
  2. Use droid exec --enabled-tools "tool1,tool2" every single time you invoke the server.
  3. Resort to creating shell aliases or wrapper scripts to automate the process.

With enabledTools, you can now configure this persistently and efficiently:

{
  "mcpServers": {
    "my-server": {
      "command": "my-mcp-server",
      "enabledTools": ["tool1", "tool2"]
    }
  }
}

This simple configuration ensures that only tool1 and tool2 are loaded, optimizing your context and streamlining your workflow. This persistent configuration eliminates the need for repetitive CLI flags or complex workarounds.

Prior Art and Industry Adoption

The concept of tool filtering is not new, and its adoption in other tools and platforms underscores its value. The existence of CLI flags like --disabled-tools and --enabled-tools in droid exec demonstrates the recognition of this need within the MCP ecosystem. Furthermore, other tools like Kiro, VS Code Copilot, and others support disabledTools in their MCP configuration schemas, highlighting the industry-wide trend towards providing granular control over tool loading.

This widespread adoption serves as a testament to the effectiveness of tool filtering in managing complex toolsets and optimizing resource utilization. By implementing enabledTools and disabledTools, MCP aligns with industry best practices and provides users with a powerful and familiar mechanism for tool management.

Conclusion: Empowering Users with Fine-Grained Control

The addition of enabledTools and disabledTools to the MCP server configuration schema represents a significant step forward in providing users with fine-grained control over their tool environment. By enabling persistent filtering of tools, these configurations address the challenges of context bloat, reduce resource consumption, and streamline workflows. This feature brings configuration file parity with existing CLI flags and empowers users to tailor their MCP environment to their specific needs.

By embracing enabledTools and disabledTools, you can optimize your MCP experience, reduce context window usage, and focus on the tools that truly matter to your work. This enhanced control translates to increased efficiency, reduced resource consumption, and a more streamlined development process.

For further reading on best practices in managing and configuring development environments, consider exploring resources like the official Configuration as Code documentation by Martin Fowler. This will provide additional insights into how to effectively manage and optimize your development workflows.