Tool Filtering

Overview

DeepIntShield provides three levels of tool filtering to control which MCP tools are available:

1. Client Configuration - Set which tools a client can execute (tools_to_execute)
2. Request Headers - Filter tools per-request via HTTP headers or context
3. Virtual Key Configuration - Control tools per-VK (Gateway only)

These levels stack: a tool must pass all applicable filters to be available.

---

Level 1: Client Configuration

The tools_to_execute field on each MCP client config defines the baseline of available tools.

Semantics

Value	Behavior
["*"]	All tools from this client are available
[] or omitted	No tools available (deny-by-default)
["tool1", "tool2"]	Only specified tools are available

Configuration

Set the baseline tool list from the MCP Gateway in the Web UI: open the client’s configuration sheet and, in the Available Tools section, enable only the tools the client should expose (for example, read_file and list_directory). This corresponds to setting tools_to_execute for the client. Click Save Changes to apply.

---

Level 2: Request-Level Filtering

Filter tools dynamically on a per-request basis using request headers.

Available Filters

Filter	Purpose
mcp-include-clients	Only include tools from specified clients
mcp-include-tools	Only include specified tools (format: clientName-toolName)

Gateway Headers

# Include only specific clients
curl -X POST https://app.deepintshield.com/v1/chat/completions \
  -H "Authorization: Bearer sk-bf-your-virtual-key" \
  -H "x-bf-mcp-include-clients: filesystem,web_search" \
  -d '...'

# Include only specific tools
curl -X POST https://app.deepintshield.com/v1/chat/completions \
  -H "Authorization: Bearer sk-bf-your-virtual-key" \
  -H "x-bf-mcp-include-tools: filesystem-read_file,web_search-search" \
  -d '...'

# Include all tools from one client, specific tools from another
curl -X POST https://app.deepintshield.com/v1/chat/completions \
  -H "Authorization: Bearer sk-bf-your-virtual-key" \
  -H "x-bf-mcp-include-tools: filesystem-*,web_search-search" \
  -d '...'

# Empty clients filter blocks ALL tools - no tools available to LLM
curl -X POST https://app.deepintshield.com/v1/chat/completions \
  -H "Authorization: Bearer sk-bf-your-virtual-key" \
  -H "x-bf-mcp-include-clients:" \
  -d '...'
# Result: No MCP tools available (deny-all)

# Empty tools filter also blocks ALL tools
curl -X POST https://app.deepintshield.com/v1/chat/completions \
  -H "Authorization: Bearer sk-bf-your-virtual-key" \
  -H "x-bf-mcp-include-tools:" \
  -d '...'
# Result: No MCP tools available (deny-all)

Wildcard Support

Pattern	Meaning
* (in include-clients)	Include all clients
clientName-* (in include-tools)	Include all tools from that client
clientName-toolName	Include specific tool

Tool Naming Convention

Important: All MCP tools follow a consistent naming convention using the prefixed format clientName-toolName:

• Tools use the format clientName-toolName (e.g., filesystem-read_file, web_search-search).
• The clientName is the name you configured for the MCP client.

This consistent naming convention ensures clear separation between tools from different clients and prevents naming conflicts across all MCP clients.

---

Level 3: Virtual Key Filtering (Gateway Only)

Virtual Keys can have their own MCP tool access configuration, which takes precedence over request-level headers.

Note

When a Virtual Key has MCP configurations, it generates the x-bf-mcp-include-tools header automatically, overriding any manually sent header.

Configuration

1. Navigate to Virtual Keys in the governance section
2. Create or edit a Virtual Key
3. In MCP Client Configurations, add the clients and tools this VK can access

For example, you might grant a support-team key only search and get_article on a knowledge_base client while allowing all tools (*) on a ticketing client.

Virtual Key MCP Config Semantics

Configuration	Result
tools_to_execute: ["*"]	All tools from this client
tools_to_execute: []	No tools from this client
tools_to_execute: ["a", "b"]	Only specified tools
Client not configured	All tools blocked from that client

Learn more in MCP Tool Filtering for Virtual Keys.

---

Filtering Logic

How Filters Combine

1. Client config is the baseline (must include the tool)
2. Request filters further narrow down (if specified)
3. VK filters override request filters (if VK has MCP configs)

Example Scenario

Setup:

• Client filesystem has tools_to_execute: ["read_file", "write_file", "delete_file"]
• Virtual Key prod-key has mcp_configs: [{ mcp_client_name: "filesystem", tools_to_execute: ["read_file"] }]

Request with prod-key:

curl -X POST https://app.deepintshield.com/v1/chat/completions \
  -H "Authorization: Bearer sk-bf-prod-key" \
  -H "x-bf-mcp-include-tools: filesystem-write_file" \  # This is IGNORED
  -d '...'

Result: Only read_file is available (VK config overrides request header)

Request with a VK that has no MCP configs:

curl -X POST https://app.deepintshield.com/v1/chat/completions \
  -H "Authorization: Bearer sk-bf-your-virtual-key" \
  -H "x-bf-mcp-include-tools: filesystem-write_file" \
  -d '...'

Result: Only write_file is available (request header applies, since the VK has no MCP config to override it)

---

Common Patterns

Read-Only Access

Allow only read operations:

{
  "tools_to_execute": ["read_file", "list_directory", "get_file_info"]
}

Environment-Based Filtering

Use different VKs for different environments:

{
  "virtual_keys": [
    {
      "name": "development",
      "mcp_configs": [
        { "mcp_client_name": "filesystem", "tools_to_execute": ["*"] },
        { "mcp_client_name": "database", "tools_to_execute": ["*"] }
      ]
    },
    {
      "name": "production",
      "mcp_configs": [
        { "mcp_client_name": "filesystem", "tools_to_execute": ["read_file"] },
        { "mcp_client_name": "database", "tools_to_execute": ["query"] }
      ]
    }
  ]
}

Per-User Tool Access

Create VKs for different user roles:

{
  "virtual_keys": [
    {
      "name": "viewer-role",
      "mcp_configs": [
        { "mcp_client_name": "documents", "tools_to_execute": ["view", "search"] }
      ]
    },
    {
      "name": "editor-role",
      "mcp_configs": [
        { "mcp_client_name": "documents", "tools_to_execute": ["view", "search", "edit", "create"] }
      ]
    },
    {
      "name": "admin-role",
      "mcp_configs": [
        { "mcp_client_name": "documents", "tools_to_execute": ["*"] }
      ]
    }
  ]
}

---

Filter Precedence

When multiple filters apply, they combine as an intersection (AND logic):

Client Config Tools ∩ Request Filters ∩ VK Filters = Available Tools

Example:

• Client config allows: [read_file, write_file, delete_file]
• Request header specifies: [read_file, write_file]
• VK config restricts to: [read_file]
• Result: Only [read_file] available

---

Debugging Tool Availability

Check Available Tools

In the MCP Gateway, the servers table shows each client’s connection state, and opening a client’s configuration sheet lists its discovered tools along with which ones are enabled in tools_to_execute. Use this to confirm a tool is present, connected, and not filtered out before debugging a request.

Check What LLM Receives

The tools included in a chat request depend on all active filters. To see what tools are available for a specific request, check the request body sent to the LLM provider in your logs or observability platform.

---

Next Steps

Virtual Key MCP Tools

Detailed VK tool configuration

Open →

Agent Mode

Configure auto-execution for filtered tools

Open →