MCP server

The MIOSA MCP (Model Context Protocol) server exposes 25 tools that let AI coding assistants create sandboxes, run commands, write files, take computer screenshots, and more — all without leaving the editor. The server speaks the MCP transport protocol, so any compliant client can drive it.

How it works

The MCP server is a thin stateless proxy. Your API key travels with every request; the server never stores credentials.

Installation

npx (no install)

npx @miosa/mcp

Global install

npm install -g @miosa/mcp
miosa-mcp --version

From source

git clone https://github.com/Miosa-osa/mcp-server
cd mcp-server && npm install && npm run build
node dist/index.js

Configuration

Claude Code

Add to ~/.claude/mcp.json (or claude mcp add if your version supports it):

{
  "mcpServers": {
    "miosa": {
      "command": "npx",
      "args": ["@miosa/mcp"],
      "env": {
        "MIOSA_API_KEY": "msk_u_..."
      }
    }
  }
}

Restart Claude Code. The MIOSA tools appear in the tool picker automatically.

Cursor

Open Cursor → Settings → MCP and add:

{
  "miosa": {
    "command": "npx @miosa/mcp",
    "env": { "MIOSA_API_KEY": "msk_u_..." }
  }
}

Windsurf

In ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "miosa": {
      "command": "npx",
      "args": ["@miosa/mcp"],
      "env": {
        "MIOSA_API_KEY": "msk_u_..."
      }
    }
  }
}

Reload Windsurf. Tools are available in the Cascade panel.

Environment variable reference

Variable	Required	Default	Description
`MIOSA_API_KEY`	Yes	—	Your `msk_u_...` key
`MIOSA_API_URL`	No	`https://api.miosa.ai`	Override for self-hosted or staging
`MIOSA_DEFAULT_TEMPLATE`	No	`miosa-sandbox`	Template used when `sandbox_create` omits `template`
`MIOSA_TIMEOUT_MS`	No	`30000`	Per-request HTTP timeout in milliseconds
`MIOSA_LOG_LEVEL`	No	`warn`	`debug`, `info`, `warn`, `error`

Tool catalog (25 tools)

Sandbox lifecycle

Tool	Description
`sandbox_create`	Boot a new sandbox. Accepts `template`, `external_workspace_id`, `external_project_id`.
`sandbox_get`	Get sandbox status, IP, template, created_at.
`sandbox_list`	List sandboxes. Filterable by `external_workspace_id`, `status`.
`sandbox_stop`	Stop a running sandbox (VM paused, not destroyed).
`sandbox_destroy`	Permanently destroy a sandbox and release compute.
`sandbox_resume`	Resume a stopped sandbox from its last state.

File I/O

Tool	Description
`file_write`	Write a file at an absolute path inside the sandbox. Creates parent directories.
`file_read`	Read a file. Returns content as a string.
`file_list`	List directory contents. Accepts `recursive` flag.
`file_delete`	Delete a file or directory.
`file_move`	Rename or move a file within the sandbox.

Execution

Tool	Description
`sandbox_exec`	Run a shell command. Returns `stdout`, `stderr`, `exit_code`.
`sandbox_exec_stream`	Run a command and stream output as SSE events.
`sandbox_exec_background`	Run a command in the background. Returns a `job_id` for status polling.
`sandbox_job_status`	Poll a background job by `job_id`.

Previews

Tool	Description
`preview_create`	Expose a sandbox port as a public HTTPS URL.
`preview_list`	List active previews for a sandbox.
`preview_destroy`	Tear down a preview URL.

Snapshots

Tool	Description
`snapshot_create`	Snapshot the current sandbox state.
`snapshot_restore`	Restore a sandbox to a named snapshot.
`snapshot_list`	List snapshots for a sandbox.

Computers

Tool	Description
`computer_create`	Boot a Linux desktop VM. Accepts `template` (`ubuntu-desktop`, `windows-11`).
`computer_screenshot`	Take a screenshot. Returns a base64-encoded PNG.
`computer_action`	Execute a desktop action: `click`, `type`, `key`, `scroll`, `double_click`.
`computer_stop`	Stop a desktop VM.

Usage examples

Create a sandbox and run a build

You: Create a Next.js sandbox and install dependencies.

The assistant calls sandbox_create({ template: "nextjs" }), then sandbox_exec({ command: "npm install" }) and streams back the output.

Write a file and preview it

You: Write this React component to /workspace/app/page.tsx and open a preview.

The assistant calls file_write, then sandbox_exec({ command: "npm run dev" }), then preview_create({ port: 3000 }) and returns the preview URL.

Screenshot → fix loop

You: Open the browser in the Ubuntu desktop and screenshot what's on screen.

The assistant calls computer_create, computer_screenshot, describes what it sees, then calls computer_action to interact.

Multi-turn file editing

You: The build failed. Check the error and fix the TypeScript types.

The assistant calls sandbox_exec({ command: "npm run build" }), reads the output, calls file_read on the failing file, patches it with file_write, and re-runs the build — all without leaving the conversation.

Troubleshooting

MIOSA_API_KEY is not set — The env var is missing from your MCP config. Confirm the env block is present in your client’s MCP JSON and that the key starts with msk_u_.

Tool calls timeout — Sandbox boots take 2–8 s on first call. Increase MIOSA_TIMEOUT_MS if your client has a short MCP timeout. Claude Code default is 30 s; Cursor default is 10 s.

403 Unauthorized — Your key is valid but lacks the required scope. Check API Keys to confirm the key has sandboxes:write and computers:write scopes.

No tools appear in Cursor — Cursor requires the MCP config to be valid JSON. Run node -e "JSON.parse(require('fs').readFileSync('~/.codeium/windsurf/mcp_config.json','utf8'))" to validate.

Security considerations

Store MIOSA_API_KEY in your client’s secret store, not in a .env file committed to git.
Use a scoped key for MCP: grant only sandboxes:write, computers:write, files:write. Never use an admin key for editor integrations.
The MCP server makes outbound HTTPS requests only. It never opens inbound ports.
Sandboxes created through MCP are subject to the same tenant-scoped authorization as API calls. The MCP server cannot access another tenant’s resources.