Session Tool Scoping

Overview

By default, every MCP session can see and execute all tools from all connected servers. Per-session tool scoping adds two optional fields to a session:

• allowed_tool_names (allowlist) — when set, only matching tools are visible
• denied_tool_names (denylist) — when set, matching tools are blocked

Both fields support wildcards (PREFIX__*) to target all tools from a server without enumerating each one.

Consider a gateway with 500 knowledge base tools from VIVI, 10 tools from HUBSPOT, and 8 tools from GMAIL:

Session Scope Levels

Every session is scoped to the authenticated user. Beyond that, you can optionally narrow the session to a specific server or bundle:

The allowed_tool_names and denied_tool_names filters then apply within whichever scope level you chose. For example, a gateway-wide session with an allowlist filters across all servers; a server-scoped session with an allowlist filters within that server's tools only.

Resolution Precedence

For each tool, the gateway evaluates three rules in order:

1. Deny always wins — if the tool matches any deny pattern, it's blocked
2. No allow list = allow all — if allowed_tool_names is null, the tool is visible
3. Must match allow — if allowed_tool_names is set, the tool must match an entry

# Pseudocode
if tool matches any denied pattern → BLOCKED
if allowed is null → VISIBLE
if tool matches any allowed pattern → VISIBLE
else → BLOCKED

How It Works

POST /api/v1/sessions
{
  "allowed_tool_names": [
    "MY_KBS__kb_finance",
    "MY_KBS__kb_hr",
    "HUBSPOT__*",
    "GMAIL__*"
  ],
  "denied_tool_names": [
    "HUBSPOT__internal_debug"
  ]
}

POST /api/v1/sessions
{
  "server_id": "a1b2c3d4-...",
  "denied_tool_names": [
    "VIVI__secret_tool",
    "VIVI__admin_reset"
  ]
}

POST /api/v1/sessions
{
  "bundle_id": "e5f6g7h8-...",
  "allowed_tool_names": [
    "MY_KBS__kb_pricing",
    "MY_KBS__kb_product_docs"
  ]
}

# tools/list — only returns allowed tools, minus denied
curl -X POST http://localhost:8000/mcp/gateway \
  -H "Authorization: Bearer mgw_usr_live_xxx" \
  -H "Mcp-Session-Id: a1b2c3d4-..." \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'

{
  "content": [{"type": "text", "text": "Tool 'HUBSPOT__internal_debug' is not in session scope"}],
  "isError": true
}

PATCH /api/v1/sessions/{session_id}
{
  "denied_tool_names": ["HUBSPOT__debug", "HUBSPOT__admin"]
}

PATCH /api/v1/sessions/{session_id}
{
  "allowed_tool_names": ["VIVI__kb_finance", "GMAIL__*"]
}

PATCH /api/v1/sessions/{session_id}
{
  "allowed_tool_names": null,
  "denied_tool_names": null
}

Wildcards

Both fields support the whole-server wildcard PREFIX__*:

Partial wildcards (e.g., HUBSPOT__search_*) are not supported and will be rejected.

Tool Name Format

Tool names must use the prefixed format: SERVER_PREFIX__tool_name or SERVER_PREFIX__*.

The prefix is derived from the server name (uppercase, spaces/hyphens replaced with underscores):

To find the correct prefixed names, call tools/list without scoping first, or use POST /api/v1/tools/search.

Scoping Behavior Reference

What Gets Filtered

Input Validation

Tool names are validated on creation and update:

• Non-empty — empty strings are rejected
• Must contain __ — the PREFIX__tool_name separator is required
• Wildcard must be whole-server — PREFIX__* is allowed, PREFIX__search_* is rejected
• No wildcards in prefix — *__tool is rejected
• SYSTEM prefix reserved — SYSTEM__anything is rejected (builtins can't be scoped)

Invalid names are rejected with a 422 Validation Error.

SDK Integration

Using the MCP Gateway Python SDK:

from mcpgateway_sdk import MCPGateway

async with MCPGateway(base_url="http://localhost:8000", api_key="mgw_usr_live_xxx") as gw:
    # Create a scoped session
    session = await gw.sessions.create(
        allowed_tool_names=[
            "VIVI__kb_finance",
            "VIVI__kb_hr",
            "VIVI__kb_legal",
            "HUBSPOT__*",
            "GMAIL__*",
        ],
        denied_tool_names=[
            "HUBSPOT__internal_debug",
        ],
    )

    # Update only the deny list (allowed list unchanged)
    session = await gw.sessions.update(
        session.id,
        denied_tool_names=["HUBSPOT__internal_debug", "HUBSPOT__admin_reset"],
    )

    # Clear all restrictions
    session = await gw.sessions.update(
        session.id,
        allowed_tool_names=None,
        denied_tool_names=None,
    )

Use Cases

Multi-tenant SaaS — One MCP server exposes 500 knowledge base tools. Each customer's agent gets a session scoped to only their knowledge bases. Customer A sees 3 tools, Customer B sees 12 — from the same server.

Role-based access — A support agent sees customer-facing tools. An admin agent sees internal tools. Same server, different session scopes.

Progressive disclosure — Start with basic tools. As the conversation reveals the user's intent, patch the session to unlock more specific tools. Keeps the initial tool list lean.

Context optimization — Reduce the tool list to only relevant tools, saving tokens and improving model accuracy.

Security isolation — Prevent agents from discovering or calling tools they shouldn't know about.

Industry Context

The MCP specification does not define per-session tool filtering. Every major platform implements this at the gateway or orchestration layer:

MCP Gateway's approach is session-level (not request-level or key-level), which means scope can change during a conversation without creating a new connection. There is an open proposal (SEP-1300) to add tool filtering to the MCP spec, but it is not yet standardized.

Related