UBOS Asset Marketplace: Isolator MCP Server - Secure Code Execution for AI Agents

In the rapidly evolving landscape of AI and Large Language Models (LLMs), the ability to securely execute code is paramount. The UBOS Asset Marketplace offers the isolator-mcp server, a robust solution designed to provide secure code execution capabilities (Python, Go, JavaScript) through containerization. This Model Context Protocol (MCP) server acts as a vital bridge, allowing AI Agents and LLM applications to safely interact with and execute code snippets in isolated environments.

Understanding the Need for Secure Code Execution

LLMs are increasingly being used in applications where they need to interact with external systems and data. This often involves executing code to perform tasks such as data analysis, system administration, or even controlling physical devices. However, executing arbitrary code from an LLM poses significant security risks. Malicious or poorly written code can compromise the entire system, leading to data breaches, system crashes, or other security incidents.

The isolator-mcp server addresses this critical need by providing a secure sandbox for code execution. By running code within isolated containers, it limits the potential damage that malicious code can cause, ensuring the overall security and stability of the system.

What is the Isolator MCP Server?

The isolator-mcp server is a TypeScript-based implementation of the Model Context Protocol (MCP). It leverages the embedded isolator Go CLI tool to create and manage secure Docker containers for code execution. LLM applications (MCP Hosts) can connect to this server and utilize its execute_code tool to safely run code snippets provided directly or loaded from predefined snippet files. The server supports multiple programming languages, including Python, Go, and JavaScript, making it a versatile solution for a wide range of AI applications.

Key Features of the Isolator MCP Server

• Secure Code Execution: The core functionality of the isolator-mcp server is to provide a secure environment for executing code. It uses Docker containers to isolate the code from the host system, preventing it from accessing sensitive data or causing damage.
• Multi-Language Support: The server supports multiple programming languages, including Python, Go, and JavaScript. This allows developers to use the language that is best suited for their specific task.
• MCP Compatibility: The isolator-mcp server is fully compatible with the Model Context Protocol (MCP). This allows it to seamlessly integrate with other MCP-compliant applications and services.
• Configurable Security: The server allows administrators to configure various security settings, such as timeout limits, resource limits, and network access. This allows them to tailor the security of the environment to their specific needs.
• Snippet Management: The server supports the use of code snippets, which are pre-defined pieces of code that can be executed by the LLM. This allows developers to create reusable code modules that can be easily integrated into their AI applications.
• Structured Results: The server returns structured results (stdout, stderr, status) via MCP, setting isError: true on tool-level failures. This allows LLMs to easily interpret the results of the code execution and take appropriate action.

Use Cases for the Isolator MCP Server

The isolator-mcp server can be used in a wide range of AI applications, including:

• AI-Powered Automation: Automate tasks by securely executing code snippets generated by LLMs. This can include tasks such as data analysis, system administration, and even controlling physical devices.
• Secure Data Analysis: Analyze sensitive data without compromising the security of the system. The isolator-mcp server ensures that the data is processed in a secure environment, preventing unauthorized access.
• Dynamic Code Generation: Generate and execute code dynamically based on user input or other factors. This allows for highly customized and interactive AI applications.
• LLM-Powered Tools: Build custom tools that leverage the power of LLMs to perform complex tasks. The isolator-mcp server provides a secure and reliable platform for executing the code required by these tools.
• Multi-Agent Systems: In scenarios where multiple AI Agents need to interact and exchange data, the isolator-mcp server can provide a secure execution environment for coordinating their actions.

Installation and Configuration

Installing and configuring the isolator-mcp server is a straightforward process. The following steps outline the basic installation process:

1. Prerequisites: Ensure that Docker, Go, Node.js, and npm are installed on the system.
2. Build isolator Go CLI: Navigate to the isolator-cli directory and build the binary using the command go build -o isolator main.go.
3. Configure isolator-mcp: Edit the isolator_config.json file to configure the server’s settings, such as the path to the isolator binary, default limits, and language images. Also, create a prompts directory and add code snippet files (e.g., hello_world.py).
4. Install Server Dependencies: Navigate to the main directory (isolator-mcp) and run npm install to install the server’s dependencies.
5. Build Server: Compile the TypeScript code using the command npm run build.
6. Configure MCP Host: Add the server to your MCP client’s settings file (e.g., cline_mcp_settings.json for the VS Code extension). Adjust the path in args if necessary.

Important Note: Ensure that the Docker images specified in isolator_config.json (e.g., python:3.11-alpine, golang:1.21-alpine) are pulled onto your system beforehand using docker pull <image_name>. The isolator tool does not automatically download missing images.

Local Development and Testing

The isolator-mcp server can be run locally for development and testing purposes without installing it via MCP Host settings. The following steps outline the process:

1. Build Go CLI: Ensure that the isolator Go CLI is built within its subdirectory using the command go build -o isolator main.go.
2. Build TS Server: In the main directory (isolator-mcp), run npm install and npm run build.
3. Configure: Make sure that isolator_config.json correctly points to the built ./isolator-cli/isolator binary via the isolatorPath key (use the absolute path).
4. Run Server: Execute the built server directly using Node: node build/index.js
5. Interact (Manual): You can manually send JSON-RPC messages (e.g., tools/list, tools/call) to the server’s standard input to test its responses. Tools like @modelcontextprotocol/inspector can also be helpful (npm run inspector).

(Remember to stop this manually run server before relying on the MCP Host to start it via the settings file.)

Architecture and Flow

The isolator-mcp server follows a well-defined architecture and flow to ensure secure and reliable code execution:

1. MCP Host Request: An LLM asks the MCP Host (e.g., VS Code Extension) to call the isolator server’s execute_code tool with arguments.
2. Server Processing (index.ts):
   • Receives the tools/call request via stdio.
   • Validates arguments using Zod.
   • Loads configuration from isolator_config.json.
   • Determines the code source: If snippet_name is provided, reads the corresponding file from the configured promptsDir and determines the language from the file extension. If entrypoint_code and language are provided, uses them directly.
   • Creates a temporary directory on the host.
   • Writes the entrypoint code and any additional_files into the temporary directory.
   • Constructs the command-line arguments for the embedded isolator Go CLI, including security flags from the config and the path to the temporary directory.
   • Spawns the isolator process using Node.js child_process.spawn.
3. Go CLI Execution (isolator-cli/isolator run):
   • Parses flags (including the new --env flag).
   • Creates a tar stream of the temporary directory contents.
   • Uses the Docker SDK to create a container with specified image, resource limits, environment variables (from --env), and security settings (NO bind mount).
   • Uses CopyToContainer to copy the tar stream into the container’s working directory.
   • Starts the container, which executes the requested command (e.g., python /workspace/hello_world.py).
   • Waits for completion, captures stdout/stderr.
   • Removes the container.
   • Prints the result (status, output, etc.) as JSON to its stdout.
4. Server Result Handling (index.ts):
   • Reads the JSON output from the finished isolator process stdout.
   • Parses the JSON result.
   • Formats the CallToolResult for MCP, combining stdout/stderr and setting isError if the Go CLI reported a non-success status.
   • Sends the result back to the MCP Host.
   • Cleans up the temporary directory on the host.
5. MCP Host Response: Relays the result back to the LLM, which then formulates a response for the user.

The execute_code Tool

The isolator-mcp server provides the execute_code tool, which is used to execute code in a secure, isolated container environment.

Description

Executes code (Python, Go, JavaScript) in a secure, isolated container environment.

Input Schema (arguments)

• language (string, optional): The programming language (e.g., “python”, “go”, “javascript”). Required if snippet_name is not provided.
• entrypoint_code (string, optional): The main code content to execute. Required if snippet_name is not provided.
• entrypoint_filename (string, optional): Filename for the main code (e.g., “main.py”, “script.js”). Defaults based on language if not provided.
• additional_files (array, optional): Array of objects, each with:
  • filename (string, required): Name of the additional file.
  • content (string, required): Content of the additional file.
• snippet_name (string, optional): Name of a pre-defined code snippet file (without extension) located in the configured promptsDir. Mutually exclusive with language and entrypoint_code.

Constraint: Either snippet_name OR both language and entrypoint_code must be provided.

Output (CallToolResult)

• content: An array containing a single TextContent object.

  • type: “text”

  • text: A string containing the combined stdout and stderr from the execution, formatted like:

    — stdout — [Actual stdout output] — stderr — [Actual stderr output]

    If an error occurred during execution (non-zero exit code, timeout), the text will be prepended with Execution Failed (status): [error message]nn.

• isError (boolean): true if the execution status reported by the isolator CLI was “error” or “timeout”, false otherwise.

(Protocol-level errors, like invalid arguments or failure to start the process, will result in a standard MCP error response instead of a CallToolResult).

UBOS: The Full-Stack AI Agent Development Platform

The isolator-mcp server is a valuable asset for developers building AI Agents on the UBOS platform. UBOS is a full-stack AI Agent development platform that empowers businesses to orchestrate AI Agents, connect them with enterprise data, build custom AI Agents with their LLM models, and create sophisticated Multi-Agent Systems.

By leveraging the isolator-mcp server within the UBOS ecosystem, developers can ensure that their AI Agents can securely execute code, enabling them to perform a wide range of tasks without compromising the security of the system. UBOS provides the tools and infrastructure needed to build, deploy, and manage AI Agents at scale, making it the ideal platform for businesses looking to harness the power of AI.

Conclusion

The isolator-mcp server is an essential component for any AI application that requires secure code execution. Its robust security features, multi-language support, and MCP compatibility make it a versatile solution for a wide range of use cases. By integrating the isolator-mcp server into their AI applications, developers can ensure that their code is executed in a safe and isolated environment, protecting their systems from potential security threats. Explore the UBOS Asset Marketplace today and discover how the isolator-mcp server can enhance your AI Agent’s capabilities.