feat: Progressive disclosure — visibility control per session

[superWorldSavior]

Motivation

A production MCP server with many tools (e.g. mcp-erpnext has 120+) floods the LLM context window. The model gets confused, picks wrong tools, or ignores relevant ones. We need a way to show only what's relevant and reveal more tools as the session context evolves.

Proposal

Add a visibility system that allows hiding/showing tools by tag, and per-session state to toggle visibility dynamically.

Registration with tags

server.registerTool(
  {
    name: "delete_all_records",
    description: "Nuclear option",
    tags: ["admin", "dangerous"],
    visible: false, // hidden by default
    inputSchema: { ... },
  },
  handler,
);

Visibility middleware

// Hide all admin tools by default
server.disable({ tags: ["admin"] });

// A gatekeeper tool that unlocks admin tools for the current session
server.registerTool(
  {
    name: "unlock_admin",
    description: "Unlock admin tools (requires authentication)",
    requiredScopes: ["admin:write"],
    inputSchema: {},
  },
  async (args, ctx) => {
    ctx.session.enable({ tags: ["admin"] });
    // Next tools/list call for this session will include admin tools
    return "Admin tools unlocked.";
  },
);

How it works

1. tools/list filters results based on session visibility state
2. Tools hidden by default don't appear until explicitly enabled
3. Visibility is per-session — one client unlocking admin doesn't affect others
4. Works with the existing middleware pipeline (auth check → scope check → visibility check)

Use cases

• Multi-tenant SaaS: free tier sees 10 tools, paid tier sees 50
• Progressive onboarding: start with basics, reveal advanced tools as the agent demonstrates competence
• Security layers: admin/destructive tools hidden until authenticated
• Context optimization: reduce token usage by only exposing relevant tool subset

Prior art

• FastMCP 3.0 visibility system (disable(tags=...) + ctx.enable_components())
• Feature flags / progressive rollout patterns

Scope

• tags and visible fields on tool/resource registration
• VisibilityFilter middleware with per-session state
• enable() / disable() methods on session context
• tools/list respects visibility state
• Documentation + examples
• Tests

[superWorldSavior]

Research notes — Priority assessment

The good part: session-scoped visibility for access control

Hiding tools by tag per session is useful for multi-tenant access control: free tier sees 10 tools, paid sees 50, admin sees all. This is a real production need.

The weak part: "progressive disclosure" for context optimization

FastMCP 3.0 markets this as a way to reduce context window bloat (too many tools → LLM gets confused). The problem is fundamental:

• If a tool is hidden from tools/list, the agent doesn't know it exists
• The agent can't request something it can't see
• You need a visible "gatekeeper" tool that says "call me to unlock admin tools"
• But the agent only calls the gatekeeper if the user explicitly asks → it's just auth with an extra step

For the real problem (120+ tools in mcp-erpnext drowning the LLM), progressive disclosure doesn't help. Better approaches:

• Meta-tool routing: "describe what you want, I'll tell you which tool to call"
• Namespace/category drill-down: agent sees groups, then explores
• These are agent-side patterns, not server-side visibility toggles

What already exists in our framework

The middleware pipeline + auth + scopes already handles the access control part. Adding a visible flag per session would be a thin layer on top, not a major feature.

Verdict

Low priority. The access control use case is real but mostly covered by existing auth middleware. The "progressive disclosure for agents" pitch is marketing — the actual UX is poor. Keeping this issue open but deprioritized.