@instantmcp/instantmcp-server

InstantMCP Server

Performance Improvements

To address timeout issues when connecting to multiple MCP servers, the following improvements have been implemented:

1. Concurrency Control

• Added processBatchedServers function to process servers in smaller batches
• Limited to 5 concurrent connections at a time (reduced from 10)
• Prevents overwhelming the system with too many simultaneous connections
• Added server limits (max 20 servers processed per request type)

2. Session Caching

• Implemented a session cache to avoid reconnecting to the same servers repeatedly
• Set a Time-To-Live (TTL) of 1 hour for cached sessions
• Significantly reduces connection overhead for frequently accessed servers

3. Progressive Timeout Strategy

• Implemented a tiered timeout system:
  • 2-second timeout for first 5 highest priority servers
  • 3-second timeout for next 5 servers
  • 3-5 second timeout for remaining servers
• Tool calls have slightly longer timeouts (5 seconds)
• Individual timeout for each server in a batch

4. Server Health Tracking

• Added system to track server health status
• Temporarily excludes servers that have failed multiple times
• Implements an automatic retry mechanism after a cooling period (10 minutes, increased from 5)
• Prevents continually trying to connect to problematic servers
• Reduced failure threshold from 3 to 2 for more aggressive filtering

5. Early Return Functionality

• Returns results as soon as a minimum threshold of items is met:
  • 30 tools
  • 15 prompts
  • 10 resources
  • 5 templates
• Prevents waiting for slower servers when sufficient data is available

6. Server Prioritization

• Ranks servers by:
  • Failure history
  • Response time performance
  • Circuit breaker status
• Processes most reliable servers first

7. Circuit Breaker Pattern

• Implements a circuit breaker to completely avoid servers that are consistently failing
• Three states for each server:
  • CLOSED (normal operation)
  • OPEN (server rejected for 30 seconds)
  • HALF-OPEN (testing if server has recovered)
• Prevents cascading failures by quickly isolating problematic servers

8. Performance Monitoring

• Tracks response times for all servers
• Uses a weighted average to prioritize recent performance
• Automatically favors faster servers in future requests

9. Disabled Logging

• All console.log and console.error statements have been commented out
• Prevents event loop blocking during logging operations
• Significantly reduces I/O overhead when processing many servers
• Improves overall server responsiveness

Usage Notes

The optimization system works automatically:

• Servers that fail twice in a row are marked as unhealthy
• Servers with repeated failures trigger circuit breaker
• Unhealthy servers are skipped in batch operations
• After 10 minutes, unhealthy servers are given another chance
• Circuit breakers reset after 30 seconds in "half-open" testing mode
• Successful operations reset the failure count
• Logging is disabled to maximize performance

Configuration

You can adjust the following parameters for your specific needs:

• SESSION_CACHE_TTL - How long to cache sessions (default: 1 hour)
• SERVER_HEALTH_CHECK_INTERVAL - How often to retry unhealthy servers (default: 10 minutes)
• MAX_FAILURES - Number of failures before marking a server unhealthy (default: 2)
• MAX_BATCH_SIZE - Number of concurrent server connections (default: 5)
• MAX_SERVERS_PER_REQUEST - Maximum number of servers to process (default: 20)
• GLOBAL_REQUEST_TIMEOUT - Default timeout for regular requests (default: 3 seconds)
• GLOBAL_TOOL_CALL_TIMEOUT - Timeout for tool calls (default: 5 seconds)
• CIRCUIT_FAILURE_THRESHOLD - Failures before opening circuit (default: 3)
• CIRCUIT_RESET_TIMEOUT - Time before testing a failed server (default: 30 seconds)
• MIN_TOOLS_THRESHOLD - Minimum number of tools before early return (default: 30)

Transport Options

The server supports multiple transport protocols:

STDIO Transport

The default transport method is STDIO, which uses standard input/output for communication:

# Start with STDIO transport (default)
npm run start

# Or explicitly specify STDIO
npm run start:stdio

SSE (Server-Sent Events) Transport

For web-based applications, you can use SSE transport:

# Start with SSE transport on port 3000 (localhost)
npm run start:sse

# Or specify a custom port and host
npm run start -- --transport sse --port 4000 --host 0.0.0.0

When using SSE transport, the server provides these endpoints:

• /sse - The SSE connection endpoint where clients establish a persistent connection
• /message - The endpoint where clients send messages to the server

The SSE transport is designed to work with the Model Context Protocol (MCP), and message passing is handled automatically by the MCP SDK.

Command Line Options

The server supports the following command line options:

Options:
  -a, --api-key <key>     API key for connecting to servers
  -l, --log-level <level> Log level (debug, info, warn, error)
  -t, --transport <type>  Transport type (stdio, sse) (default: "stdio")
  -p, --port <number>     Port for SSE server (if using SSE transport) (default: "3000")
  -h, --host <host>       Host for SSE server (if using SSE transport) (default: "localhost")
  -h, --help              Display help for command