feat(gateway): add tools_include and tools_exclude filters

Add fnmatch glob-based tool filtering to gateways. When a gateway is
refreshed, registered, updated or activated, the discovered tools are
filtered against optional include/exclude patterns:

- tools_include: whitelist – only tools matching at least one pattern
  are kept
- tools_exclude: blacklist – tools matching any pattern are removed
- When both are set, include is applied first, then exclude

This enables splitting a single MCP backend into multiple gateways with
different tool subsets (e.g. one gateway for ticket tools, another for
project tools) without requiring upstream server changes.

Changes:
- db.py: tools_include/tools_exclude JSON columns on Gateway model
- schemas.py: fields on GatewayCreate, GatewayUpdate, GatewayRead
- gateway_service.py: _apply_tool_filters() helper + 4 call sites
- export_service.py / import_service.py: export/import support
- admin.py: form parsing for create and edit flows
- admin_ui JS: comma-separated input → JSON array conversion
- templates/admin.html: input fields in create and edit forms
- Alembic migration for the new columns

Signed-off-by: Olivier Gintrand <olivier.gintrand@forterro.com>

Author: Olivier Gintrand

mcpgateway/admin.py

@@ -12008,6 +12008,24 @@ async def admin_add_gateway(request: Request, db: Session = Depends(get_db), use
         else:
             passthrough_headers = None
 
+        # Handle tools_include filter
+        tools_include_str = str(form.get("tools_include", ""))
+        tools_include: Optional[list[str]] = None
+        if tools_include_str and tools_include_str.strip():
+            try:
+                tools_include = orjson.loads(tools_include_str)
+            except (orjson.JSONDecodeError, ValueError):
+                tools_include = [p.strip() for p in tools_include_str.split(",") if p.strip()]
+
+        # Handle tools_exclude filter
+        tools_exclude_str = str(form.get("tools_exclude", ""))
+        tools_exclude: Optional[list[str]] = None
+        if tools_exclude_str and tools_exclude_str.strip():
+            try:
+                tools_exclude = orjson.loads(tools_exclude_str)
+            except (orjson.JSONDecodeError, ValueError):
+                tools_exclude = [p.strip() for p in tools_exclude_str.split(",") if p.strip()]
+
         # Auto-detect OAuth: if oauth_config is present and auth_type not explicitly set, use "oauth"
         auth_type_from_form = str(form.get("auth_type", ""))
         LOGGER.info(f"DEBUG: auth_type from form: '{auth_type_from_form}', oauth_config present: {oauth_config is not None}")
@@ -12058,6 +12076,8 @@ async def admin_add_gateway(request: Request, db: Session = Depends(get_db), use
             oauth_config=oauth_config,
             one_time_auth=form.get("one_time_auth", False),
             passthrough_headers=passthrough_headers,
+            tools_include=tools_include,
+            tools_exclude=tools_exclude,
             visibility=visibility,
             ca_certificate=ca_certificate,
             ca_certificate_sig=sig if sig else None,
@@ -12204,6 +12224,24 @@ async def admin_edit_gateway(
         else:
             passthrough_headers = None
 
+        # Handle tools_include filter
+        tools_include_str = str(form.get("tools_include", ""))
+        tools_include: Optional[List[str]] = None
+        if tools_include_str and tools_include_str.strip():
+            try:
+                tools_include = orjson.loads(tools_include_str)
+            except (orjson.JSONDecodeError, ValueError):
+                tools_include = [p.strip() for p in tools_include_str.split(",") if p.strip()]
+
+        # Handle tools_exclude filter
+        tools_exclude_str = str(form.get("tools_exclude", ""))
+        tools_exclude: Optional[List[str]] = None
+        if tools_exclude_str and tools_exclude_str.strip():
+            try:
+                tools_exclude = orjson.loads(tools_exclude_str)
+            except (orjson.JSONDecodeError, ValueError):
+                tools_exclude = [p.strip() for p in tools_exclude_str.split(",") if p.strip()]
+
         # Parse OAuth configuration - support both JSON string and individual form fields
         oauth_config_json = str(form.get("oauth_config"))
         oauth_config: Optional[dict[str, Any]] = None
@@ -12309,6 +12347,8 @@ async def admin_edit_gateway(
             auth_query_param_value=str(form.get("auth_query_param_value", "")) or None,
             one_time_auth=form.get("one_time_auth", False),
             passthrough_headers=passthrough_headers,
+            tools_include=tools_include,
+            tools_exclude=tools_exclude,
             oauth_config=oauth_config,
             visibility=visibility,
             owner_email=user_email,

mcpgateway/admin_ui/formSubmitHandlers.js

@@ -790,6 +790,28 @@ export const handleEditGatewayFormSubmit = async function (e) {
 
     formData.append("passthrough_headers", JSON.stringify(passthroughHeaders));
 
+    // Process tools_include - convert comma-separated string to JSON array
+    const toolsIncludeString = formData.get("tools_include") || "";
+    const toolsInclude = toolsIncludeString
+      .split(",")
+      .map((pattern) => pattern.trim())
+      .filter((pattern) => pattern.length > 0);
+    if (toolsInclude.length > 0) {
+      formData.delete("tools_include");
+      formData.append("tools_include", JSON.stringify(toolsInclude));
+    }
+
+    // Process tools_exclude - convert comma-separated string to JSON array
+    const toolsExcludeString = formData.get("tools_exclude") || "";
+    const toolsExclude = toolsExcludeString
+      .split(",")
+      .map((pattern) => pattern.trim())
+      .filter((pattern) => pattern.length > 0);
+    if (toolsExclude.length > 0) {
+      formData.delete("tools_exclude");
+      formData.append("tools_exclude", JSON.stringify(toolsExclude));
+    }
+
     // Handle OAuth configuration
     // NOTE: OAuth config assembly is now handled by the backend (mcpgateway/admin.py)
     // The backend assembles individual form fields into oauth_config with proper field names
@@ -884,6 +906,28 @@ export const handleEditA2AAgentFormSubmit = async function (e) {
 
     formData.append("passthrough_headers", JSON.stringify(passthroughHeaders));
 
+    // Process tools_include - convert comma-separated string to JSON array
+    const editToolsIncludeString = formData.get("tools_include") || "";
+    const editToolsInclude = editToolsIncludeString
+      .split(",")
+      .map((pattern) => pattern.trim())
+      .filter((pattern) => pattern.length > 0);
+    if (editToolsInclude.length > 0) {
+      formData.delete("tools_include");
+      formData.append("tools_include", JSON.stringify(editToolsInclude));
+    }
+
+    // Process tools_exclude - convert comma-separated string to JSON array
+    const editToolsExcludeString = formData.get("tools_exclude") || "";
+    const editToolsExclude = editToolsExcludeString
+      .split(",")
+      .map((pattern) => pattern.trim())
+      .filter((pattern) => pattern.length > 0);
+    if (editToolsExclude.length > 0) {
+      formData.delete("tools_exclude");
+      formData.append("tools_exclude", JSON.stringify(editToolsExclude));
+    }
+
     // Handle auth_headers JSON field
     const authHeadersJson = formData.get("auth_headers");
     if (authHeadersJson) {

mcpgateway/admin_ui/gateways.js

@@ -576,6 +576,26 @@ export const editGateway = async function (gatewayId) {
       }
     }
 
+    // Handle tools_include
+    const toolsIncludeField = safeGetElement("edit-gateway-tools-include");
+    if (toolsIncludeField) {
+      if (gateway.toolsInclude && Array.isArray(gateway.toolsInclude)) {
+        toolsIncludeField.value = gateway.toolsInclude.join(", ");
+      } else {
+        toolsIncludeField.value = "";
+      }
+    }
+
+    // Handle tools_exclude
+    const toolsExcludeField = safeGetElement("edit-gateway-tools-exclude");
+    if (toolsExcludeField) {
+      if (gateway.toolsExclude && Array.isArray(gateway.toolsExclude)) {
+        toolsExcludeField.value = gateway.toolsExclude.join(", ");
+      } else {
+        toolsExcludeField.value = "";
+      }
+    }
+
     openModal("gateway-edit-modal");
     applyVisibilityRestrictions(["edit-gateway-visibility"]); // Disable public radio if restricted, preserve checked state
     console.log("✓ Gateway edit modal loaded successfully");

mcpgateway/alembic/versions/e25e538ec346_add_gateway_tool_filters.py

@@ -0,0 +1,48 @@
+# Copyright contributors to the MCP Context Forge project
+# SPDX-License-Identifier: Apache-2.0
+
+"""Add tools_include and tools_exclude columns to gateways
+
+Revision ID: e25e538ec346
+Revises: z1a2b3c4d5e6
+Create Date: 2025-07-01 10:00:00.000000
+
+"""
+
+# Third-Party
+from alembic import op
+import sqlalchemy as sa
+
+# revision identifiers, used by Alembic.
+revision = "e25e538ec346"
+down_revision = "z1a2b3c4d5e6"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    """Add tools_include and tools_exclude JSON columns to gateways table."""
+    conn = op.get_bind()
+    dialect = conn.dialect.name
+
+    if dialect == "sqlite":
+        # SQLite does not support IF NOT EXISTS for ADD COLUMN;
+        # inspect existing columns and skip if already present.
+        from sqlalchemy import inspect as sa_inspect
+
+        inspector = sa_inspect(conn)
+        existing = {col["name"] for col in inspector.get_columns("gateways")}
+        if "tools_include" not in existing:
+            op.add_column("gateways", sa.Column("tools_include", sa.JSON(), nullable=True))
+        if "tools_exclude" not in existing:
+            op.add_column("gateways", sa.Column("tools_exclude", sa.JSON(), nullable=True))
+    else:
+        # PostgreSQL supports ADD COLUMN IF NOT EXISTS
+        op.execute("ALTER TABLE gateways ADD COLUMN IF NOT EXISTS tools_include JSON")
+        op.execute("ALTER TABLE gateways ADD COLUMN IF NOT EXISTS tools_exclude JSON")
+
+
+def downgrade() -> None:
+    """Remove tools_include and tools_exclude columns from gateways table."""
+    op.drop_column("gateways", "tools_exclude")
+    op.drop_column("gateways", "tools_include")

mcpgateway/db.py

@@ -4667,6 +4667,13 @@ def team(self) -> Optional[str]:
     # - 'direct_proxy': All RPC calls are proxied directly to remote MCP server with no database caching
     gateway_mode: Mapped[str] = mapped_column(String(20), nullable=False, default="cache", comment="Gateway mode: 'cache' (database caching) or 'direct_proxy' (pass-through mode)")
 
+    # Tool filtering: include/exclude patterns (fnmatch glob syntax)
+    # - tools_include: only tools matching at least one pattern are imported (whitelist)
+    # - tools_exclude: tools matching any pattern are excluded (blacklist)
+    # - If both are set, include is applied first, then exclude
+    tools_include: Mapped[Optional[List[str]]] = mapped_column(JSON, nullable=True, default=None, comment="Glob patterns to include tools (whitelist)")
+    tools_exclude: Mapped[Optional[List[str]]] = mapped_column(JSON, nullable=True, default=None, comment="Glob patterns to exclude tools (blacklist)")
+
     # Relationship with OAuth tokens
     oauth_tokens: Mapped[List["OAuthToken"]] = relationship("OAuthToken", back_populates="gateway", cascade="all, delete-orphan")
 

mcpgateway/schemas.py

@@ -2706,6 +2706,10 @@ class GatewayCreate(BaseModelWithConfigDict):
     # Gateway mode configuration
     gateway_mode: str = Field(default="cache", description="Gateway mode: 'cache' (database caching, default) or 'direct_proxy' (pass-through mode with no caching)", pattern="^(cache|direct_proxy)$")
 
+    # Tool filtering: fnmatch glob patterns to include/exclude tools during refresh
+    tools_include: Optional[List[str]] = Field(None, description="Glob patterns to whitelist tools (only matching tools are imported)")
+    tools_exclude: Optional[List[str]] = Field(None, description="Glob patterns to blacklist tools (matching tools are excluded)")
+
     @field_validator("gateway_mode", mode="before")
     @classmethod
     def default_gateway_mode(cls, v: Optional[str]) -> str:
@@ -3042,6 +3046,10 @@ class GatewayUpdate(BaseModelWithConfigDict):
     # Gateway mode configuration
     gateway_mode: Optional[str] = Field(None, description="Gateway mode: 'cache' (database caching, default) or 'direct_proxy' (pass-through mode with no caching)", pattern="^(cache|direct_proxy)$")
 
+    # Tool filtering: fnmatch glob patterns to include/exclude tools during refresh
+    tools_include: Optional[List[str]] = Field(None, description="Glob patterns to whitelist tools (only matching tools are imported)")
+    tools_exclude: Optional[List[str]] = Field(None, description="Glob patterns to blacklist tools (matching tools are excluded)")
+
     # CA certificate configuration for custom TLS trust
     ca_certificate: Optional[str] = Field(None, description="Custom CA certificate for TLS verification")
     ca_certificate_sig: Optional[str] = Field(None, description="Signature of the custom CA certificate")
@@ -3411,6 +3419,10 @@ class GatewayRead(BaseModelWithConfigDict):
     # Gateway mode configuration
     gateway_mode: str = Field(default="cache", description="Gateway mode: 'cache' (database caching, default) or 'direct_proxy' (pass-through mode with no caching)")
 
+    # Tool filtering: fnmatch glob patterns to include/exclude tools during refresh
+    tools_include: Optional[List[str]] = Field(None, description="Glob patterns to whitelist tools (only matching tools are imported)")
+    tools_exclude: Optional[List[str]] = Field(None, description="Glob patterns to blacklist tools (matching tools are excluded)")
+
     _normalize_visibility = field_validator("visibility", mode="before")(classmethod(lambda cls, v: _coerce_visibility(v)))
 
     # Tool count (populated from the tools relationship; 0 when not loaded)

mcpgateway/services/export_service.py

@@ -511,6 +511,12 @@ async def _export_gateways(self, db: Session, tags: Optional[List[str]], include
                 "passthrough_headers": gateway.passthrough_headers or [],
             }
 
+            # Tool filtering patterns
+            if gateway.tools_include:
+                gateway_data["tools_include"] = gateway.tools_include
+            if gateway.tools_exclude:
+                gateway_data["tools_exclude"] = gateway.tools_exclude
+
             # Handle authentication data securely - use batch-fetched values
             if gateway.auth_type and gateway.auth_value:
                 if gateway.auth_value == settings.masked_auth_value:
@@ -937,6 +943,12 @@ async def _export_selected_gateways(self, db: Session, gateway_ids: List[str], u
                 "passthrough_headers": db_gateway.passthrough_headers or [],
             }
 
+            # Tool filtering patterns
+            if db_gateway.tools_include:
+                gateway_data["tools_include"] = db_gateway.tools_include
+            if db_gateway.tools_exclude:
+                gateway_data["tools_exclude"] = db_gateway.tools_exclude
+
             # Include auth data directly from DB (already have raw values)
             if db_gateway.auth_type:
                 gateway_data["auth_type"] = db_gateway.auth_type