Skip to content
Ephemeral Sandbox mascot — a Siamese kitten peeking out of its wooden sandbox
Browse docs

Interfaces

MCP servers

Register one management, runtime, or observability catalog per MCP server.

On this page+

Choose a tool set

sandbox-mcp projects exactly one fixed semantic catalog into each stdio process. There is no combined set and no combined sandbox mcp command.

Management tools

sandbox-mcp --set management

Eight tools for discovery, lifecycle, compaction, and export.

Open the tool reference

Observability tools

sandbox-mcp --set observability

Five read-only tools for health, telemetry, resources, and layers.

Open the tool reference

Build and register

Build one executable, then register three separately named server processes with absolute paths.

Shell
cargo build -p sandbox-mcp --bin sandbox-mcp
MCP client configuration
{
  "mcpServers": {
    "ephemeral-os-management": {
      "command": "/absolute/path/to/target/debug/sandbox-mcp",
      "args": ["--set", "management"]
    },
    "ephemeral-os-runtime": {
      "command": "/absolute/path/to/target/debug/sandbox-mcp",
      "args": ["--set", "runtime"]
    },
    "ephemeral-os-observability": {
      "command": "/absolute/path/to/target/debug/sandbox-mcp",
      "args": ["--set", "observability"]
    }
  }
}

Static configurations must also provide gateway authentication through the process environment or explicit flags. The repository helper below installs token-loading launchers instead of embedding the credential in JSON.

Codex setup

bin/setup-codex-mcp verifies Codex and Cargo, creates or validates the shared token, builds the server, replaces registrations named ephemeral-os-management, ephemeral-os-runtime, and ephemeral-os-observability, then lists them.

Shell
bin/setup-codex-mcp

Restart Codex or open a new session after registration so it discovers the tool definitions.

Stdio and protocol

The client launches sandbox-mcp as a long-running stdio child. Do not write diagnostic text to that protocol stream. The server reports MCP protocol version 2025-06-18 and advertises tools only.

Implemented MCP surface

Initialization, initialized notification, ping, tool listing, and tool calls. Prompts, resources, templates, and completion return method-not-found.

Schemas and results

Tool definitions are generated from the same typed catalog as CLI help. Input schemas reject additional properties and publish semantic property names such as sandbox_id, workspace_session_id, and yield_time_ms.

CallToolResult shape
{
  "content": [],
  "structuredContent": { "images": ["ubuntu:24.04"] },
  "isError": false
}

The detailed pages show the actual published schema beside each tool and call out places where handler validation is narrower than generated JSON Schema.

Errors and progress

Local request-building errors, gateway transport failures, and gateway error envelopes all become tool results with isError: true. The structured error envelope is retained in structuredContent. The current server does not emit MCP progress notifications; use the operation result and follow-up observability calls.

Public boundaries

Internal workspace lifecycle, capture, remount, LayerStack export, and export-chunk operations are not MCP tools. file_list is the deliberate daemon HTTP-only exception. See the operations reference and web console boundary before integrating a surface outside these catalogs.

58 results