Improve context management

[cbcoutinho]

The Nextcloud MCP Server provides 50+ tools with extensive docstrings that provide a lot of information to LLMs. Large foundation models such as GPT-4, Claude Opus 4.5, etc. can handle the context, but this is inefficient and is unusable by smaller models without severely constraining the number of tools/apps provided by the server.

How can we optimize context management with the MCP server? Some ideas:

• Configure MCP clients to connect to the MCP server in various configurations (e.g. only expose notes, deck, or read-only tools)
• Deploy multiple copies of the MCP server with specific apps enabled
• Deploy an MCP gateway or reverse proxy in front of the MCP server
• Dynamically load tools into an MCP session
• Move tool documentation to a separate MCP tool so that an MCP client can request additional information (e.g. Azure DevOps MCP Server uses this approach)
• Others?

[cbcoutinho]

@claude provide your thoughts on this topic, considering the current number of tools and their associated docstrings/documentation and function signatures (e.g. using Pydantic models for serialization). Expand on any implications of increasing both the number of supported apps, the number of tools for existing apps, as well as more high-level workflow-oriented tools that the MCP server could expose in the future, and how this should be incorporated into planning how to deal with context management more broadly

[cbcoutinho]

From Claude Opus 4.5:

This is a thoughtful discussion about a real and growing challenge in the MCP ecosystem. Here are my thoughts:

The Core Problem

The Nextcloud MCP Server exposes 50+ tools, each with detailed docstrings, Pydantic model schemas for parameters, and function signatures. While this richness is great for capability, it creates a significant context overhead. Every tool definition consumes tokens before a single user message is processed, which creates two issues: cost/latency for large models, and outright unusability for smaller models with tighter context windows.

Evaluating the Proposed Solutions

1. Configurable tool subsets / multiple server deployments
This is pragmatic and works today. The downside is operational complexity—users must decide upfront which capabilities they need, and switching requires reconfiguration. It's a good near-term solution but doesn't scale elegantly.

2. MCP gateway or reverse proxy
Interesting for enterprise deployments where you want centralized policy control, but it adds infrastructure overhead and doesn't fundamentally solve the context problem—it just moves where the filtering decision is made.

3. Dynamic tool loading
This is promising. The MCP protocol already supports tools/list being called at any time. A server could expose a meta-tool like enable_app(app_name) that dynamically adds tools to the session. The challenge is that most MCP clients don't expect the tool list to change mid-session, so client support would need to catch up.

4. Separate documentation tool (Azure DevOps pattern)
This is elegant. Instead of embedding full documentation in tool descriptions, you provide minimal signatures and a get_tool_help(tool_name) tool. The LLM can request detailed docs only when needed. This dramatically reduces baseline context while preserving capability. The tradeoff is an extra round-trip when the model needs to learn how to use a tool.

Implications of Growth

As you add more apps, tools per app, and higher-level workflow tools, the problem compounds:

• Linear growth in tools means linear growth in context overhead with current approaches
• Workflow tools (e.g., "create a project with a deck board, shared folder, and calendar") are valuable but add yet more definitions
• Pydantic models with nested structures can be particularly verbose in JSON Schema form

At some point, even large models will feel the pressure—not from capability limits, but from the opportunity cost of context spent on tool definitions rather than conversation history or retrieved documents.

Recommendations

I'd suggest a layered approach:

1. Short-term: Implement app-based filtering via server configuration. Document recommended profiles (e.g., "notes-only", "collaboration", "full").

2. Medium-term: Adopt the lazy documentation pattern. Keep tool signatures minimal and move detailed docs/examples to an on-demand help tool. This could cut context usage by 60-80% while maintaining discoverability.

3. Long-term: Explore tool "categories" or "capabilities" that the LLM can request. For example, the server exposes a list_capabilities() tool that returns high-level categories, and the LLM can call load_capability("deck") to bring those tools into scope. This requires client support for dynamic tool lists but aligns with where the MCP ecosystem seems to be heading.

4. Consider a tiered tool hierarchy: Expose commonly-used tools by default, and gate less common ones behind explicit requests. Usage analytics could inform which tools belong in which tier.

The discussion is asking the right questions at the right time—solving this before the tool count doubles will be much easier than retrofitting later.

[cbcoutinho]

Response from Gemini 3 Pro

This is a highly relevant discussion that touches on one of the most immediate scaling challenges for the Model Context Protocol (MCP): the "Context vs. Capability" trade-off.
As MCP servers grow from simple utilities to full application interfaces (like Nextcloud), sending the full schema for 50+ tools in every request becomes unsustainable.
Here are my thoughts on the discussion and the proposed solutions:

1. The "Lazy Documentation" Approach is the Strongest Medium-Term Solution
   I agree with the "Claude Opus 4.5" analysis in the thread that Solution 5 (Move tool documentation to a separate MCP tool) is the most elegant immediate fix.

• Why it works: Most LLMs act on "intent" first. They don't need to know the exact parameter constraints of files_share to know they want to share a file.
• The Workflow: The server exposes a minimal signature (e.g., files_share(path: str, ...)). If the model is confused or hallucinates parameters, it can call a get_tool_help(tool="files_share") tool.
• Efficiency: This shifts the "cost" from Every Request (huge system prompt) to On Demand (extra round-trip only when necessary). For 50+ tools, this is a massive net saving.

2. Dynamic Loading (Solution 3) is the Ideal "North Star"
   While dynamic loading is the most flexible, it faces a practical hurdle: Client Inertia.
   Current MCP clients (like Claude Desktop or IDE extensions) generally expect the tool list to be static during a session.

• The "Meta-Tool" Pattern: Creating a tool like enable_capability(category="deck") is brilliant. It mimics how humans load software libraries. You don't import every Python library at startup; you import what you need.
• The Risk: If the client UI doesn't visually update to show the new tools, the user might be confused, though the LLM will "know" they are available.

3. A Missing Piece: Hierarchical Discovery
   One approach not fully expanded upon in the discussion is Hierarchical Discovery (similar to a filesystem).
   Instead of a flat list of 50 tools or complex dynamic loading, the server could expose one tool initially: list_capabilities().

• Step 1: Model sees list_capabilities.
• Step 2: Model calls it and sees ['files', 'deck', 'notes', 'calendar'].
• Step 3: Model realizes it needs to schedule a meeting and requests tools for calendar.
  This is less "dynamic code loading" and more "progressive disclosure," which fits the agentic workflow well.
  Summary
  The discussion correctly identifies that context management is an architectural problem, not just a prompt engineering one.
• For now: The maintainer should likely pursue Solution 1 (Configurable Profiles) as a stop-gap because it requires zero changes to the MCP spec or clients—it's just env vars.
• Next: Implement Solution 5 (Lazy Docs). The overhead of an extra network call to fetch help is negligible compared to the latency and cost of processing 20k tokens of unused tool definitions on every turn.