Add MCP experimental feature to beta (#936)

<!-- CURSOR_SUMMARY -->
> [!NOTE]
> Adds beta MCP support to JS/Python SDKs with template auto-selection,
config POST, MCP URL helpers, and codegen for MCP types/schemas.
> 
> - **SDKs (Beta MCP support)**:
>   - **JS SDK**:
> - Add `McpServer` types and export; extend `Sandbox.betaCreate` with
`mcp` option that auto-selects `mcp-gateway-v0`, configures MCP via POST
`/config` on port `50005` with retries, and expose `betaGetMcpUrl()`.
> - Add `wait(ms)` util; generate MCP types from `spec/mcp-server.json`;
new `generate:mcp` script and dev dep `json-schema-to-typescript`.
>   - **Python SDK**:
> - Generate and export `McpServer` (TypedDict); extend sync/async
`beta_create` with `mcp` option, auto-select default MCP template, POST
MCP config with retries, and add `beta_get_mcp_url()`; define `mcp_port`
and `default_mcp_template`.
> - Makefile: add `generate-mcp` target; include
`datamodel-code-generator` in tooling; update lockfile/pyproject deps.
> - **Tooling**:
> - Add `spec/mcp-server.json` schema; update codegen Dockerfile to
install `datamodel-code-generator`.
> -
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
cf3f175. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

---------

Co-authored-by: Jonas Scholz <Jonas.Scholz@bbscholz.de>

Author: ValentaTomas

.changeset/fifty-comics-tease.md

@@ -0,0 +1,6 @@
+---
+'@e2b/python-sdk': patch
+'e2b': patch
+---
+
+Add experimental MCP functionality to beta

apps/web/src/components/Layout.tsx

@@ -23,7 +23,7 @@ export function Layout({
 
   return (
     <SectionProvider
-      sections={relativePathname ? allSections[relativePathname] ?? [] : []}
+      sections={relativePathname ? (allSections[relativePathname] ?? []) : []}
     >
       <div
         className={clsx('h-[100vh] w-full', {

codegen.Dockerfile

@@ -34,7 +34,7 @@ ENV PATH="/go/bin:${PATH}"
 
 # Install Python deps (e2b-openapi-python-client is patched version to fix issue with explode)
 # https://github.com/openapi-generators/openapi-python-client/pull/1296
-RUN pip install black==23.7.0 pyyaml==6.0.2 e2b-openapi-python-client==0.26.2
+RUN pip install black==23.7.0 pyyaml==6.0.2 e2b-openapi-python-client==0.26.2 datamodel-code-generator==0.34.0
 
 # Install Node.js and npm
 RUN apt-get update && \

packages/cli/src/utils/templateSort.ts

@@ -1,7 +1,7 @@
 import * as sdk from 'e2b'
 
 export function sortTemplatesAliases<
-  E extends sdk.components['schemas']['Template']['aliases']
+  E extends sdk.components['schemas']['Template']['aliases'],
 >(aliases: E) {
   aliases?.sort()
 }

packages/js-sdk/package.json

@@ -32,6 +32,7 @@
     "generate:api": "python ./../../spec/remove_extra_tags.py sandboxes templates auth && openapi-typescript ../../spec/openapi_generated.yml -x api_key --array-length --alphabetize --output src/api/schema.gen.ts",
     "generate:envd": "cd ../../spec/envd && buf generate --template buf-js.gen.yaml\n",
     "generate:envd-api": "openapi-typescript ../../spec/envd/envd.yaml -x api_key --array-length --alphabetize --output src/envd/schema.gen.ts",
+    "generate:mcp": "json2ts -i ./../../spec/mcp-server.json -o src/sandbox/mcp.d.ts --unreachableDefinitions --style.singleQuote --no-style.semi",
     "generate-ref": "./scripts/generate_sdk_ref.sh",
     "check-deps": "knip",
     "update-deps": "ncu -u && pnpm i",
@@ -53,6 +54,7 @@
     "@vitest/browser": "^3.1.1",
     "dotenv": "^16.4.5",
     "eslint": "^8.57.1",
+    "json-schema-to-typescript": "^15.0.4",
     "knip": "^5.43.6",
     "npm-check-updates": "^16.14.20",
     "npm-run-all": "^4.1.5",
@@ -102,4 +104,4 @@
   "browserslist": [
     "defaults"
   ]
-}
+}

packages/js-sdk/src/index.ts

@@ -46,6 +46,8 @@ export type {
   SandboxPaginator,
 } from './sandbox/sandboxApi'
 
+export type { McpServer } from './sandbox/mcp'
+
 export type {
   ProcessInfo,
   CommandRequestOpts,

packages/js-sdk/src/sandbox/index.ts

@@ -9,6 +9,7 @@ import {
 } from '../connectionConfig'
 import { EnvdApiClient, handleEnvdApiError } from '../envd/api'
 import { createRpcLogger } from '../logs'
+import { wait } from '../utils'
 import { Commands, Pty } from './commands'
 import { Filesystem } from './filesystem'
 import {
@@ -64,6 +65,7 @@ export interface SandboxUrlOpts {
  */
 export class Sandbox extends SandboxApi {
   protected static readonly defaultTemplate: string = 'base'
+  protected static readonly defaultMcpTemplate: string = 'mcp-gateway-v0'
   protected static readonly defaultSandboxTimeoutMs = DEFAULT_SANDBOX_TIMEOUT_MS
 
   /**
@@ -90,6 +92,7 @@ export class Sandbox extends SandboxApi {
   readonly sandboxDomain: string
 
   protected readonly envdPort = 49983
+  protected readonly mcpPort = 50005
 
   protected readonly connectionConfig: ConnectionConfig
   protected readonly envdAccessToken?: string
@@ -301,8 +304,16 @@ export class Sandbox extends SandboxApi {
   ): Promise<InstanceType<S>> {
     const { template, sandboxOpts } =
       typeof templateOrOpts === 'string'
-        ? { template: templateOrOpts, sandboxOpts: opts }
-        : { template: this.defaultTemplate, sandboxOpts: templateOrOpts }
+        ? {
+            template: templateOrOpts,
+            sandboxOpts: opts,
+          }
+        : {
+            template: templateOrOpts?.mcp
+              ? this.defaultMcpTemplate
+              : this.defaultTemplate,
+            sandboxOpts: templateOrOpts,
+          }
 
     const config = new ConnectionConfig(sandboxOpts)
     if (config.debug) {
@@ -313,13 +324,54 @@ export class Sandbox extends SandboxApi {
       }) as InstanceType<S>
     }
 
-    const sandbox = await SandboxApi.createSandbox(
+    const sandboxInfo = await SandboxApi.createSandbox(
       template,
       sandboxOpts?.timeoutMs ?? this.defaultSandboxTimeoutMs,
       sandboxOpts
     )
 
-    return new this({ ...sandbox, ...config }) as InstanceType<S>
+    const sandbox = new this({ ...sandboxInfo, ...config }) as InstanceType<S>
+
+    if (sandboxOpts?.mcp) {
+      const mcpConfigUrl = `${
+        config.debug ? 'http' : 'https'
+      }://${sandbox.getHost(sandbox.mcpPort)}/config`
+
+      const signal = config.getSignal()
+
+      let mcpConfigured = false
+
+      // TODO: The MCP config seems to succeed on first attempt, but we are keeping the retry logic here for now.
+      for (let i = 0; i < 5; i++) {
+        try {
+          const res = await fetch(mcpConfigUrl, {
+            method: 'POST',
+            body: JSON.stringify(sandboxOpts?.mcp),
+            signal,
+          })
+
+          if (res.ok) {
+            mcpConfigured = true
+
+            break
+          }
+        } catch (e) {
+          config.logger?.warn?.(`Failed to configure MCP server: ${e}`)
+        }
+
+        await wait(250)
+      }
+
+      if (!mcpConfigured) {
+        await sandbox.kill()
+
+        throw new SandboxError(
+          `Failed to configure MCP server. The sandbox template '${template}' might not be configured with MCP gateway inside.`
+        )
+      }
+    }
+
+    return sandbox
   }
 
   /**
@@ -519,6 +571,17 @@ export class Sandbox extends SandboxApi {
     return await SandboxApi.betaPause(this.sandboxId, opts)
   }
 
+  /**
+   * @beta This feature is in beta and may change in the future.
+   *
+   * Get the MCP URL for the sandbox.
+   *
+   * @returns MCP URL for the sandbox.
+   */
+  betaGetMcpUrl(): string {
+    return `https://${this.getHost(this.mcpPort)}/mcp`
+  }
+
   /**
    * Get the URL to upload a file to the sandbox.
    *