Server Auto-Discovery
Relevant source files
The following files were used as context for generating this wiki page:
Server Auto-Discovery is a core mechanism within the MCP Code Execution Server that enables the bridge to identify, parse, and utilize external Model Context Protocol (MCP) servers without manual pre-registration. This feature facilitates a "Zero-Context Discovery" pattern, where the LLM only loads the tool schemas it specifically needs, reducing context window bloat from potentially 30,000 tokens down to roughly 200 tokens.
Sources: README.md:88-100, ARCHITECTURE.md:81-86
Discovery Architecture
The discovery process is handled by the MCPBridge class, which scans a prioritized list of local and global configuration paths to find JSON or TOML definitions of MCP servers. Once discovered, these servers are made available for lazy loading within the sandboxed environment.
Priority-Based Path Scanning
The system uses a list of ConfigSource objects to define where to look for configurations. Priority is determined by the order in the CONFIG_SOURCES list, where earlier entries or specific user-defined paths take precedence.
Sources: mcp_server_code_execution_mode.py:180-245, README.md:462-480
| Location Description | Path Example (macOS/Linux) | Priority |
|---|---|---|
| User MCPs | ~/MCPs | Highest |
| Standard MCP | ~/.config/mcp/servers | High |
| Local Project | ./mcp-servers | Medium |
| Claude CLI | ~/.claude.json | Medium |
| VS Code Workspace | ./.vscode/mcp.json | Low |
| VS Code Global | ~/Library/Application Support/Code/User/settings.json | Lowest |
Sources: mcp_server_code_execution_mode.py:180-245, GUIDE.md:126-150
Discovery Logic Flow
The following diagram illustrates the sequence from the initial scan to the availability of server metadata for the sandbox.
The bridge automatically skips any configuration entry that appears to start the mcp-server-code-execution-mode bridge itself to prevent recursive launch loops.
Sources: mcp_server_code_execution_mode.py:1016-1060, README.md:493-498
Discovery Workflow and Runtime Helpers
The discovery system is exposed to the LLM through a set of runtime helpers within the mcp.runtime module. This allows the agent to interactively explore available tools.
Two-Stage Discovery Pattern
- Enumerate Servers: The LLM calls
runtime.discovered_servers()to see which server configurations exist on the host without fetching their full tool schemas. - Hydrate Documentation: When a specific capability is needed, the LLM calls
runtime.query_tool_docs(server)to fetch the detailed JSON schemas for that specific server's tools.
Sources: README.md:129-140, GUIDE.md:321-335
Runtime Helper Functions
The mcp.runtime module is injected into the sandbox and provides the following key functions for discovery:
| Function | Purpose | Type |
|---|---|---|
discovered_servers(detailed=False) | Lists all servers found during the scan. | Sync |
search_tool_docs(query, limit=5) | Performs a fuzzy search across all loaded server tool descriptions. | Async |
query_tool_docs(server, tool=None) | Retrieves full schemas for a specific server or tool. | Async |
list_loaded_server_metadata() | Returns metadata for servers currently active in the run. | Sync |
Sources: mcp_server_code_execution_mode.py:750-860, tests/test_entrypoint.py:270-300
Server Metadata and Configuration
When a server is discovered and subsequently loaded, the bridge extracts specific metadata to facilitate proxying.
Metadata Extraction
The bridge parses the mcpServers object found in configuration files. Each server entry includes:
- Command: The executable to run (e.g.,
npx,python3). - Args: Command-line arguments passed to the server.
- Env: Environment variables required by the server.
- CWD: (Optional) The working directory for the host process.
Sources: mcp_server_code_execution_mode.py:1078-1110, GUIDE.md:215-230
Multi-Server Interaction Sequence
This diagram shows how the bridge handles discovery and tool invocation across multiple servers.
Sources: README.md:520-540, ARCHITECTURE.md:75-95
Implementation Details
Configuration Parsing
The _load_server_config method handles the heavy lifting of reading files and extracting the mcpServers block. It supports both JSON and TOML formats, provided the environment supports tomllib.
# mcp_server_code_execution_mode.py:1041-1055
with open(path, "rb") as f:
if path.suffix == ".toml":
if tomllib:
data = tomllib.load(f)
else:
return {}
else:
data = json.load(f)
mcp_servers = data.get("mcpServers", {})
Sources: mcp_server_code_execution_mode.py:1041-1055
Fuzzy Search Indexing
To support efficient discovery without full schema preloading, the bridge maintains a search index of tool keywords (server names, tool names, and descriptions). This index is marked "dirty" and rebuilt whenever new servers are loaded or tool schemas are hydrated.
Sources: mcp_server_code_execution_mode.py:1198-1225, GUIDE.md:465-485
Summary
Server Auto-Discovery transforms the MCP Code Execution Server from a static tool-runner into a dynamic gateway. By scanning standardized local and global paths, it allows developers to aggregate dozens of MCP servers into a single interface. The discovery-first architecture ensures that token usage remains constant (approx. 200 tokens) regardless of the total number of tools available, solving the "MCP Token Bankruptcy" problem.
Sources: README.md:102-115, STATUS.md:38-45