mcp-sandbox

MCP Sandbox automatically converts a JavaScript module into an MCP (Model Context Protocol) server. It analyzes the module to reflect available functions, infers parameter types, and exposes the functions as MCP tools with endpoints for JSON-RPC, REST, and Server-Sent Events. You can start the server via the provided CLI and then interact with the generated MCP endpoints to discover tools, execute them, and retrieve an MCP configuration file. The server exposes a JSON-RPC endpoint at /mcp/jsonrpc, a REST tool explorer at /tools, and a separate /mcp-config endpoint for the generated configuration. Use the MCP Inspector as needed to test streams and tool calls through the configured transport. Tools are discovered automatically with names and docstrings derived from the module, and you can call them with the appropriate arguments via the REST or JSON-RPC interfaces.

Prerequisites

• Node.js and npm (or pnpm) installed on your machine
• Access to install global CLI or use npx to run the CLI

Install options

1. Global CLI installation (recommended for persistent access)

   • npm install -g @mcp-sandbox/cli
   • Then start a module server with: mcp-sandbox start ./path/to/your-module.js

2. Use via npx (no global install required)

   • npx -y @mcp-sandbox/cli start ./path/to/your-module.js

3. In a project (local usage)

   • npm install @mcp-sandbox/core @mcp-sandbox/cli
   • Use the CLI locally: npx @mcp-sandbox/cli start ./path/to/your-module.js

Notes

• Replace ./path/to/your-module.js with the actual module you want to expose. The module should export functions you want accessible via MCP.
• Ensure your module’s functions have clear JSDoc comments and sensible default parameters to improve reflection and type inference.

Tips and common issues:

• Port conflicts: The server defaults to port 3000. If you have another service on that port, specify a different port via the CLI options (e.g., mcp-sandbox start ./module.js --port 4000).
• Timeouts and memory: Adjust the execution timeout and memory limits if your functions are heavy or long-running. Use the CLI or programmatic options to configure these values.
• Security: VM isolation helps, but avoid exposing sensitive operations. Use restricted modules and validate inputs; rely on the sandbox’s input validation and controlled requires.
• MCP Inspector: For testing with the inspector, point it to http://localhost:3000/mcp/jsonrpc and use the Streamable HTTP transport.
• Configuration file: The server can emit an mcp-config.json which clients can consume to integrate with your MCP ecosystem.