Session Tool Scoping
Control which tools each agent session can see — per-session allowlists for multi-tenant isolation, role-based access, and progressive disclosure.
Overview
The MCP specification defines sessions as stateful connections between a client and a server, identified by a Mcp-Session-Id header. MCP Gateway extends this standard concept with per-session tool scoping — the ability to restrict which tools are visible and callable within a specific session.
Without scoping, every session sees every enabled tool across all connected servers. This is fine for single-agent setups, but breaks down in production:
- A server has 500 knowledge base tools, but Agent A should only see 3
- Different customers need access to different tool subsets
- An agent should progressively gain access to tools as the conversation evolves
Session tool scoping solves this at the gateway layer — no changes to your MCP servers required.
Session scoping filters all tool surfaces: tools/list in LIST mode, SEARCH_TOOLS, EXECUTE_TOOL, and direct tools/call. An agent literally cannot discover or call tools outside its session scope.
How It Works
Create a scoped session
When starting a new agent session, pass allowed_tool_names with the prefixed tool names the agent should see. The gateway creates the session and enforces the scope across all tool operations.
POST /api/v1/sessions
{
"server_id": "your-server-uuid",
"allowed_tool_names": [
"MY_KBS__search_kb_pricing",
"MY_KBS__search_kb_product_docs"
]
}Omit allowed_tool_names (or set to null) for unrestricted access — fully backwards compatible.
Agent uses tools normally
The agent connects via the gateway endpoint and uses tools as usual. It has no awareness that scoping is applied — it simply sees fewer tools in tools/list and SEARCH_TOOLS results.
Update scope at runtime (optional)
Need to grant or revoke tool access mid-conversation? Patch the session:
PATCH /api/v1/sessions/{session_id}
{
"allowed_tool_names": [
"MY_KBS__search_kb_pricing",
"MY_KBS__search_kb_product_docs",
"MY_KBS__search_kb_competitor_analysis"
]
}Set to null to remove all restrictions.
What Gets Filtered
| Gateway Path | Scoped? | Details |
|---|---|---|
tools/list (LIST mode) | Yes | Only allowed tools appear in the tool list |
SEARCH_TOOLS | Yes | Vector search results filtered to allowed tools only |
EXECUTE_TOOL | Yes | Calls to tools outside the allowlist are rejected |
tools/call (direct) | Yes | Direct MCP tool calls also respect the session scope |
SYSTEM__ builtins | Always visible | Gateway meta-tools (SEARCH_TOOLS, EXECUTE_TOOL) are never filtered |
/mcp/servers/{id} (direct server) | Not scoped | Direct server connections bypass session scoping by design |
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.
Development vs production — Development sessions see all tools for testing. Production sessions are scoped to the curated set.
Industry Context
The MCP specification does not define per-session tool filtering. Every major platform implements this at the gateway or orchestration layer:
| Platform | Approach |
|---|---|
| OpenAI | allowed_tools per API request |
| AWS Bedrock | Cedar policies per principal |
| Kong AI Gateway | Consumer Group ACLs |
| LiteLLM | Allowlists per API key |
| MCP Gateway | allowed_tool_names per session |
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.