Resource completion performance: Consider client-side caching and fuzzy filtering

Issue Description

The current MCP resource completion system calls the server for every keystroke, which creates performance and scalability issues for servers that need to make API calls to external services (like Vault, Kubernetes, etc.).

Current Behavior

• MCP clients call server completion endpoint for every character typed
• Server must perform fresh API calls for each completion request
• No mechanism to indicate completion caching behavior to clients
• Results in excessive load on both MCP servers and backend services

Example Impact

In our Vault roles resource, we:

1. Query Vault's /sys/auth endpoint to list all auth methods
2. For each auth method, query /auth/{method}/roles?list=true
3. Process and format results
4. Return to MCP client

This happens for every keystroke: "k", "ku", "kub", "kube", "kuber", etc.

Proposed Solutions

Option 1: Server-hints for caching

• Allow MCP servers to indicate in completion responses whether results should be cached
• Include cache TTL hints in completion responses
• Extend MCP protocol to support caching metadata

Option 2: Minimum search length protocol support

• Add MCP protocol configuration for minimum search length before triggering server calls
• Allow servers to specify minimum completion length in resource templates
• E.g., don't call server until user has typed at least 2-3 characters

Option 3: Completion result metadata

• Add metadata to completion responses indicating:
  • Whether results are static vs dynamic
  • Suggested cache duration
  • Whether incremental search is beneficial

Option 4: Protocol-level completion optimization

• Define completion strategies in MCP spec (immediate, debounced, cached, etc.)
• Allow servers to declare preferred completion behavior
• Provide guidance for client implementations

Current Server-Side Workarounds

We've implemented server-side optimizations:

• Early filtering to avoid unnecessary API calls
• Result limits to cap response size
• Early exit when sufficient results found

But this still results in redundant work on every keystroke, and servers have no way to communicate caching preferences to clients.

Use Cases Affected

Any resource completion that involves:

• External API calls (Vault, Kubernetes, AWS, etc.)
• Database queries
• File system operations
• Network requests

Environment

• MCP TypeScript SDK (server-side)
• Resource completion with external API dependencies
• Any MCP client implementation

Protocol Considerations

This affects the core MCP protocol design around resource completion. Solutions should focus on:

• Protocol extensions for completion metadata/hints
• Server capability declaration for completion behavior
• Standardized completion optimization patterns
• MCP specification guidance for efficient completion

The goal is to provide servers a way to communicate completion characteristics to clients, allowing clients to implement appropriate optimization strategies.

Would appreciate thoughts on the best approach for server-declared completion optimization!

Start by reviewing the MCP resource completion protocol and the TypeScript SDK's completion implementation; the issue names no specific files or tests. Compare the proposed caching, minimum-length, metadata, and strategy options, then define a focused protocol direction and its client/server behavior before implementation. Done should include agreed protocol guidance or extensions and coverage for the affected completion behavior.