Tool Filtering

Overview

DeepIntShield provides three related controls for MCP tools:

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 - A persisted per-key execution allow-list (Gateway only)

Connection and request filters shape the model-visible catalogue. A Virtual Key binding is also a hard execution condition: visibility never grants permission to invoke a tool. When Agentic-New GAF is enabled, its exact-workspace decision is the final independent execution boundary.

---

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 Agentic → MCP Registry 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-ds-your-virtual-key" \
  -H "x-deepintshield-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-ds-your-virtual-key" \
  -H "x-deepintshield-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-ds-your-virtual-key" \
  -H "x-deepintshield-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-ds-your-virtual-key" \
  -H "x-deepintshield-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-ds-your-virtual-key" \
  -H "x-deepintshield-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 Authorization (Gateway Only)

Virtual Keys have their own persisted MCP client/tool binding. Every gateway request requires an active key, and a key with no MCP binding has no MCP tools. An include header cannot grant a missing key binding.

Note

Treat x-deepintshield-mcp-include-tools as catalogue shaping, not authorization. Actual execution revalidates the current key row, exact client and configuration fingerprint, and the key’s persisted tool binding. With GAF enabled, the governed agent, Registry action, OpenFGA relationships, and any Command Authority approval must also return Allow.

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 connection baseline and cannot be expanded by a request.
2. Request filters shape which baseline tools are presented for that request; they are not grants.
3. VK bindings are revalidated at execution and cannot be expanded by a request header.
4. Canonical GAF, when enabled, must return an exact Allow for the resolved agent, client, tool, action, configuration, and arguments.

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-ds-prod-key" \
  -H "x-deepintshield-mcp-include-tools: filesystem-write_file" \
  -d '...'

Result: The header does not authorize write_file. Execution is denied because the key is bound only to read_file, even if a model-visible catalogue or caller-supplied tool definition names write_file.

Request with a VK that has no MCP configs:

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

Result: No MCP tools are available. A key without an MCP binding is deny-all, and a request header cannot create one.

---

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": ["*"] }
      ]
    }
  ]
}

---

Visibility and execution intersection

At execution time, the authoritative controls combine as an intersection:

Client Config ∩ Current VK Binding ∩ Canonical GAF Allow = Executable Tool

Request include headers may narrow or shape discovery, but they never add an execution permission. For 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] can execute, and GAF can still deny or require approval for that exact call

---

Debugging Tool Availability

Check Available Tools

In Agentic → MCP Registry, 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 →