---
title: "MCP Tool Filtering"
description: "Control which MCP tools are available for each Virtual Key."
icon: "grid-2"
---

## Overview

MCP Tool Filtering allows you to control which tools are available to AI models on a per-request basis using Virtual Keys (VKs). By configuring a VirtualKey, you can create a strict allow-list of MCP clients and tools, ensuring that only approved tools can be executed.

Make sure you have at least one MCP client set up. Read more about it [here](../../mcp/overview).

## How It Works

The filtering logic is determined by the Virtual Key's configuration:

1.  **No MCP Configuration on Virtual Key (Default)**
    - If a Virtual Key has no specific MCP configurations, **no MCP tools are available** (deny-by-default).
    - You must explicitly add MCP client configurations to allow tools.

2.  **With MCP Configuration on Virtual Key**
    - When you configure MCP clients on a Virtual Key, its settings take full precedence.
    - Bifrost automatically generates an `x-bf-mcp-include-tools` header based on your VK configuration (unless `disable_auto_tool_inject` is enabled or the caller already sent the header). This acts as a strict allow-list for the request.
    - If the caller already includes an `x-bf-mcp-include-tools` header, auto-injection is skipped — but the VK allow-list is enforced at inference time and still enforced again at MCP tool execution time.

For each MCP client associated with a Virtual Key, you can specify the allowed tools:
- **Select specific tools**: Only the chosen tools from that client will be available.
- **Use `*` wildcard**: All available tools from that client will be permitted.
- **Leave tool list empty**: All tools from that client will be **blocked**.
- **Do not configure a client**: All tools from that client will be **blocked** (if other clients are configured).

## Setting MCP Tool Restrictions

<Tabs group="mcp-tool-restrictions">
<Tab title="Web UI">

You can configure which tools a Virtual Key has access to via the UI.

1.  Go to **Virtual Keys** page.
2.  Create/Edit virtual key
![Virtual Key MCP Tool Restrictions](../../media/ui-virtual-key-mcp-filter.png)
3.  In **MCP Client Configurations** section, add the MCP client you want to restrict the VK to
4.  Select the specific tools to allow, or choose **Allow All Tools** to permit all current and future tools from that client (stored as `*`). Leaving the list empty blocks all tools for that client.
5.  Click on the **Save** button

</Tab>
<Tab title="API">

You can configure this via the REST API when creating (`POST`) or updating (`PUT`) a virtual key.

**Create Virtual Key:**
```bash
curl -X POST http://localhost:8080/api/governance/virtual-keys \
  -H "Content-Type: application/json" \
  -d '{
    "name": "vk-for-billing-support",
    "mcp_configs": [
      {
        "mcp_client_name": "billing-client",
        "tools_to_execute": ["check-status"]
      },
      {
        "mcp_client_name": "support-client",
        "tools_to_execute": ["*"]
      }
    ]
  }'
```

**Update Virtual Key:**
```bash
curl -X PUT http://localhost:8080/api/governance/virtual-keys/{vk_id} \
  -H "Content-Type: application/json" \
  -d '{
    "mcp_configs": [
      {
        "mcp_client_name": "billing-client",
        "tools_to_execute": ["check-status"]
      },
      {
        "mcp_client_name": "support-client",
        "tools_to_execute": ["*"]
      }
    ]
  }'
```

**Behavior:**
- The virtual key can only access the `check-status` tool from `billing-client`.
- It can access all tools from `support-client`.
- Any other MCP client is implicitly blocked for this key.

</Tab>

<Tab title="config.json">

You can also define MCP tool restrictions directly in your `config.json` file. The `mcp_configs` array under a virtual key should reference the MCP client by name.

```json
{
  "governance": {
    "virtual_keys": [
      {
        "id": "vk-billing-support-only",
        "name": "VK for Billing and Support",
        "mcp_configs": [
          {
            "mcp_client_name": "billing-client",
            "tools_to_execute": ["check-status"]
          },
          {
            "mcp_client_name": "support-client",
            "tools_to_execute": ["*"]
          }
        ]
      }
    ]
  }
}
```
</Tab>
</Tabs>

## Example Scenario

**Available MCP Clients & Tools:**
- **`billing-client`**: with tools `[create-invoice, check-status]`
- **`support-client`**: with tools `[create-ticket, get-faq]`

<Tabs>
<Tab title="VK with Full Access">
**Configuration:**
- `billing-client` -> Allowed Tools: `[*]` (wildcard)
- `support-client` -> Allowed Tools: `[*]` (wildcard)

**Result:**
A request with this Virtual Key can access all four tools: `create-invoice`, `check-status`, `create-ticket`, and `get-faq`.

</Tab>
<Tab title="VK with Partial Access">
**Configuration:**
- `billing-client` -> Allowed Tools: `[check-status]`
- `support-client` -> Not configured

**Result:**
A request with this Virtual Key can only access the `check-status` tool. All other tools are blocked.

</Tab>
<Tab title="VK with No Tools">
**Configuration:**
- `billing-client` -> Allowed Tools: `[]` (empty list)

**Result:**
A request with this Virtual Key cannot access any tools. All tools from all clients are blocked.
</Tab>
</Tabs>

<Note>
When a Virtual Key has MCP configurations, Bifrost enforces the allow-list at both inference time and MCP tool execution time. Auto-injection of the `x-bf-mcp-include-tools` header is skipped if the caller already provides it or if `disable_auto_tool_inject` is enabled — but the VK's restrictions are always applied regardless. You can still use the `x-bf-mcp-include-clients` header to filter MCP clients per request.
</Note>