# Issue: docker mcp tools ls scales linearly - needs parallel execution and caching

[angelbruce]

Issue: docker mcp tools ls scales linearly - needs parallel execution and caching

Summary

docker mcp tools ls command scales linearly with the number of MCP tools. As the MCP catalog grows, this creates a severe bottleneck for frontend tools (OpenCode, Claude, Cursor, etc.) that rely on tool enumeration during initialization.

Current Behavior

• 49 tools: ~18 seconds
• 174 tools: ~60+ seconds
• 272 tools: ~100+ seconds (1m41s)

Each additional tool adds ~0.3-0.5 seconds due to serial container startup.

Problem

With 270+ MCP servers now available in the MCP catalog, and growing:

• Frontend clients (OpenCode, Claude Desktop, Cursor, etc.) timeout waiting for tool lists (default 30s timeout)
• Users cannot utilize the full MCP ecosystem
• Performance degrades as more tools are added
• This will become increasingly critical as the MCP catalog expands

Root Cause

The Gateway appears to serialize container startup and tool enumeration:

For each MCP server:
  - Launch container
  - Wait for initialization
  - Get tool definitions
  - Serialize results

This creates a linear O(n) dependency.

Proposed Solutions

1. Parallel Container Execution (High Impact)

• Launch multiple MCP server containers concurrently (e.g., 5-10 in parallel)
• Use goroutines/async patterns to handle concurrent stdio communication
• Expected improvement: 5-10x faster (18s → 2-4s for 49 tools)

2. Tool Metadata Caching (High Impact)

• Cache tool definitions after first enumeration
• Only refresh on configuration changes
• Provide TTL-based invalidation option
• Expected improvement: 2nd+ calls: <100ms

3. Incremental/Lazy Loading

• Paginate tool results (e.g., --limit N --offset M)
• Load tools on-demand instead of all-at-once
• Allows clients to timeout gracefully on subset

4. Async API Endpoint

• Provide docker mcp tools ls --watch for streaming results
• Clients can display tools as they load instead of waiting for complete list
• Better UX for large tool sets

Impact

This is critical for the success of the MCP ecosystem as:

• The catalog now has 270+ tools and growing
• Frontend integrations depend on tool enumeration
• Without optimization, users will disable tools or abandon MCP entirely
• Performance directly affects adoption rate

Reproduction

# Test with current setup
time docker mcp tools ls > /dev/null

# Expected: sub-2 second response even with 200+ tools

Environment

• Docker Desktop 4.50+
• MCP Toolkit with 49-272+ MCP servers enabled
• OpenCode and other frontend clients

Related

• OpenCode timeout issues with large tool sets
• MCP catalog growth (now 270+ servers)
• Frontend integration performance

---

Submitted by: User feedback (OpenCode/MCP integration testing)
Use Case: Full MCP ecosystem adoption, frontend tool integration
Severity: High (blocks usability of large tool sets)