Working Directory Management (cwd)

Relevant source files

The following files were used as context for generating this wiki page:

• mcp_server_code_execution_mode.py
• GUIDE.md
• README.md
• ARCHITECTURE.md
• tests/test_entrypoint.py

Working Directory Management (cwd) in the MCP Code Execution Server is a critical configuration property that defines the filesystem context in which host-managed MCP servers are executed. It ensures that servers—particularly those that are project-specific or file-oriented—can correctly locate and interact with their intended target directories.

This system bridges the gap between the isolated container sandbox and the host environment by allowing developers to specify where individual tool processes should start. Agents interacting with the bridge can programmatically discover these directories to make informed decisions about file paths during code execution.

Host-Side Configuration

The cwd property is an optional field defined within the JSON configuration for individual MCP servers. When the bridge initiates a connection to a specific server, it utilizes this path to spawn the underlying process.

Configuration Logic

During the discovery phase, the bridge parses server configurations from multiple sources (such as ~/.config/mcp/servers/). The cwd value is extracted and stored within the MCPServerInfo data structure.

• Optionality: If cwd is absent, the host starts the MCP server process in the bridge's default working directory.
• Validation: The bridge attempts to validate the existence of the directory during server loading but does not fail the startup if the directory is missing, opting to log a warning instead.

Sources: mcp_server_code_execution_mode.py:465-472, mcp_server_code_execution_mode.py:917-932, GUIDE.md:278-294

Runtime Discovery and Inspection

For Large Language Model (LLM) agents, knowing the cwd of a tool is essential for constructing valid file paths. The bridge exposes this metadata through the mcp.runtime helper module inside the sandbox.

Metadata Flow

1. Server Loading: When a server is loaded, its metadata (including cwd) is cached.
2. RPC Request: The agent calls discovery helpers like runtime.describe_server().
3. Metadata Injection: The bridge serializes the cached cwd and returns it to the sandbox.

Key Discovery Functions

Function	Description	Source
runtime.describe_server(name)	Returns a dictionary containing server metadata, including the cwd field.	mcp_server_code_execution_mode.py:808-809
runtime.list_loaded_server_metadata()	Returns a tuple of all metadata for servers currently loaded in the session.	mcp_server_code_execution_mode.py:811-812

Sources: GUIDE.md:295-303, tests/test_entrypoint.py:38-51

Implementation Details

The bridge handles cwd primarily within the MCPServerInfo class and the PersistentMCPClient.

Data Structures

The MCPServerInfo NamedTuple stores the working directory as an optional string.

@dataclass
class MCPServerInfo:
    name: str
    command: str
    args: List[str]
    env: Dict[str, str]
    cwd: Optional[str] = None
    description: str = ""

Sources: mcp_server_code_execution_mode.py:465-472

Process Spawning

When PersistentMCPClient starts, it passes the cwd to StdioServerParameters. This ensures the stdio_client context manager initiates the sub-process in the correct location.

params = StdioServerParameters(
    command=self.server_info.command,
    args=self.server_info.args,
    env=self.server_info.env or None,
    cwd=self.server_info.cwd or None,
)

Sources: mcp_server_code_execution_mode.py:647-652

Best Practices for Agents

Agents should not assume a working directory exists or is set to a specific path. The recommended workflow for agents requiring directory context is:

1. Describe: Call runtime.describe_server(name) to fetch metadata.
2. Check: Verify if the cwd key exists and is not null.
3. Fallback: If missing, assume the bridge's default directory or prompt the user for configuration.

Sources: GUIDE.md:304-311, ARCHITECTURE.md:46-56

Summary

Working Directory Management provides the necessary filesystem context for host-side MCP servers. By defining cwd in host configurations and exposing it via discovery helpers in the sandbox, the system enables agents to perform complex, path-dependent operations safely and accurately across the host-container boundary.