Tool Discovery Implementation

DeployStack Satellite implements automatic tool discovery from MCP servers across both HTTP/SSE remote endpoints and stdio subprocess servers. This unified system provides dynamic tool availability without manual configuration, enabling MCP clients to discover and execute tools through the satellite's interface.

Current Implementation: Tool discovery fully supports both HTTP/SSE remote MCP servers and stdio subprocess servers through a unified architecture. The UnifiedToolDiscoveryManager coordinates discovery across both transport types, merging tools into a single cache for seamless client access.

For information about the overall satellite architecture, see Satellite Architecture Design. For details about the MCP transport protocols that expose discovered tools, see MCP Transport Protocols.

Technical Overview

Unified Discovery Architecture

Tool discovery operates through three coordinated managers that handle different transport types and merge results:

┌─────────────────────────────────────────────────────────────────────────────────┐
│                     Unified Tool Discovery Architecture                         │
│                                                                                 │
│  ┌─────────────────────────────────────────────────────────────────┐           │
│  │              UnifiedToolDiscoveryManager                        │           │
│  │                                                                 │           │
│  │  • Coordinates both HTTP and stdio discovery                   │           │
│  │  • Merges tools from both managers                            │           │
│  │  • Single interface for MCP clients                           │           │
│  └─────────────────────────────────────────────────────────────────┘           │
│                            │                  │                                 │
│                            ▼                  ▼                                 │
│  ┌───────────────────────────┐    ┌───────────────────────────┐               │
│  │ RemoteToolDiscoveryManager │    │ StdioToolDiscoveryManager │               │
│  │                           │    │                           │               │
│  │ • HTTP/SSE servers        │    │ • stdio subprocesses      │               │
│  │ • Startup discovery       │    │ • Post-spawn discovery    │               │
│  │ • SSE parsing             │    │ • JSON-RPC over stdin/out │               │
│  │ • Static configuration    │    │ • Process lifecycle aware │               │
│  └───────────────────────────┘    └───────────────────────────┘               │
└─────────────────────────────────────────────────────────────────────────────────┘

Core Components

UnifiedToolDiscoveryManager:

Coordinates discovery across HTTP/SSE and stdio transport types
Merges tools from both managers into unified cache
Routes discovery requests based on transport type
Provides single interface for MCP protocol handlers

RemoteToolDiscoveryManager:

Queries remote HTTP/SSE MCP servers during startup
Parses Server-Sent Events responses
Maintains in-memory cache with namespacing
Handles differential configuration updates

StdioToolDiscoveryManager:

Discovers tools from stdio subprocess MCP servers
Executes discovery after process spawn and handshake
Automatically clears tools on process termination
Tracks tools by server with namespacing

Discovery Process by Transport Type

HTTP/SSE Discovery (Startup)

Remote HTTP/SSE servers are discovered during satellite initialization:

Startup → Config Load → HTTP Servers → Query tools/list → Cache Tools → Ready
    │           │             │               │               │          │
 Init      Enabled Only   POST Request    Parse Response   Namespace   Serve

HTTP Discovery Flow:

Load enabled HTTP/SSE servers from dynamic configuration
Query each server with tools/list JSON-RPC request
Parse SSE or JSON responses
Cache tools with namespacing (server_slug-tool_name)
Expose through MCP transport endpoints

stdio Discovery (Post-Spawn)

stdio subprocess servers are discovered after process spawning:

Process Spawn → Handshake → Running → Discover Tools → Cache → Auto-Cleanup
      │             │          │            │           │           │
  Backend Cmd   Initialize   Status     tools/list   Namespace   On Exit

stdio Discovery Flow:

Process spawned via Backend command
MCP handshake completes (initialize + initialized)
Discovery triggered automatically after handshake
Tools cached with namespacing (server_slug-tool_name)
Tools cleared automatically on process termination

Discovery Timing Differences

HTTP/SSE (Eager):

Discovered at startup before serving requests
All HTTP tools available immediately
Configuration changes trigger rediscovery

stdio (Lazy):

Discovered after process spawn completes
Tools become available post-handshake
Process termination removes tools automatically

Tool Caching Strategy

Unified Cache Design

Both transport types use identical caching and namespacing:

interface UnifiedCachedTool {
  serverName: string;           // Installation name
  originalName: string;         // Tool name from server
  namespacedName: string;       // server_slug-tool_name
  description: string;          // Tool description
  inputSchema: object;          // JSON Schema
  transport: 'stdio' | 'http';  // Transport type for routing
  discoveredAt?: Date;          // Discovery timestamp (HTTP only)
}

Cache Characteristics:

Unified Namespace: Same format across both transport types
Memory Storage: No persistent storage or database
Automatic Cleanup: stdio tools removed on process exit
Conflict Prevention: server_slug ensures unique names

Namespacing Strategy

Both HTTP and stdio tools use identical namespacing:

HTTP Tool Example:
  Server Slug: "context7"
  Original: "resolve-library-id"
  Namespaced: "context7-resolve-library-id"

stdio Tool Example:
  Server Slug: "filesystem" (extracted from "filesystem-john-abc123")
  Original: "read_file"
  Namespaced: "filesystem-read_file"

Namespacing Rules:

Format: {server_slug}-{originalToolName}
HTTP: Uses server_slug from configuration
stdio: Extracts slug from installation name
Routing: Internal server names used for team isolation
User Display: Friendly namespaced names shown to clients

For team-based server resolution, see Team Isolation Implementation.

Configuration Management

Dynamic Configuration Updates

The unified manager handles configuration changes intelligently:

Differential Updates:

Only discovers tools for added/modified servers
Preserves tools for unchanged servers
Removes tools for deleted servers
Minimizes network overhead and latency

Configuration Sources:

HTTP/SSE: Static configuration from Backend polling
stdio: Dynamic spawning via Backend commands
Both: Support three-tier configuration system

Tool Execution Flow

Transport-Aware Routing

Tool execution routes to the correct transport based on discovery:

MCP Client → tools/call → Parse Name → Lookup Tool → Route by Transport
    │            │            │            │              │
  Request    Namespaced   Extract Slug   Get Cache    stdio/HTTP/SSE

HTTP Transport:

Routes to remote HTTP/SSE endpoint
Uses HTTP Proxy Manager
Handles SSE streaming responses

stdio Transport:

Routes to local subprocess
Uses ProcessManager JSON-RPC
Communicates over stdin/stdout

Error Handling & Recovery

Discovery Failures

Both managers implement graceful failure handling:

HTTP Discovery:

Server unreachable → Skip and continue
Parse errors → Log and skip malformed tools
Timeout → Mark server as failed

stdio Discovery:

Process not running → Error with status check
No tools returned → Empty array (valid response)
Communication failure → Process restart logic

Automatic Cleanup

stdio tools are automatically managed:

Process Lifecycle:

Spawn: Tools discovered after handshake
Running: Tools available for execution
Terminate: Tools removed from cache automatically

Development Considerations

Debugging Support

The debug endpoint shows tools from both transport types:

curl http://localhost:3001/api/status/debug

Debug Information:

Tools grouped by transport type (HTTP/stdio)
Tools grouped by server name
Discovery statistics for both managers
Process status for stdio servers

Security Notice: The debug endpoint exposes detailed system information. Disable in production with DEPLOYSTACK_STATUS_SHOW_MCP_DEBUG_ROUTE=false.

Testing Strategies

Unified Testing:

# Test tool listing (shows both HTTP and stdio tools)
curl -X POST http://localhost:3001/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":"1","method":"tools/list","params":{}}'

# Test HTTP tool execution
curl -X POST http://localhost:3001/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":"2","method":"tools/call","params":{"name":"context7-resolve-library-id","arguments":{"libraryName":"react"}}}'

# Test stdio tool execution
curl -X POST http://localhost:3001/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":"3","method":"tools/call","params":{"name":"filesystem-read_file","arguments":{"path":"/tmp/test.txt"}}}'

Performance Characteristics

HTTP/SSE Performance

Discovery Time: 2-5 seconds at startup
Memory: ~1KB per tool
Overhead: Single HTTP request per server
Caching: Persistent until configuration change

stdio Performance

Discovery Time: 1-2 seconds post-spawn
Memory: ~1KB per tool
Overhead: Single JSON-RPC request per process
Caching: Automatic cleanup on process exit

Scalability

Combined Limits:

No hard server limit for either transport
Memory-bound by total tool count
HTTP: Limited by network connection pool
stdio: Limited by system process limits

Implementation Status: Tool discovery is fully operational for both HTTP/SSE remote servers and stdio subprocess servers. The unified manager successfully coordinates discovery, merges tools, and routes execution requests to the appropriate transport.

Future Enhancements

Dynamic Capabilities

Planned Features:

Runtime refresh for HTTP servers without restart
Configuration hot-reload for both transport types
Health monitoring with automatic server detection
Tool versioning support

Advanced Features

Under Consideration:

Load balancing across multiple server instances
Circuit breakers for automatic failure recovery
Detailed usage and performance analytics
Cache persistence for faster startup (HTTP only)

The unified tool discovery implementation provides a solid foundation for multi-transport MCP server integration while maintaining simplicity and reliability for development and production use.

On this page