first commit

2026-04-26 21:52:23 +03:00
commit 880f412e2c
2662 changed files with 866266 additions and 0 deletions
--- a/docs/features/governance/mcp-tools.mdx
+++ b/docs/features/governance/mcp-tools.mdx
@@ -0,0 +1,160 @@
+---
+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>