MCP server

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

Two ways to use MCP

Hosted (zero install) - recommended

Point any MCP-compatible client directly at the MIOSA API. No pip, no npm, nothing to install or run locally.

https://api.miosa.ai/api/v1/mcp

This is the easiest path. Your API key travels in the Authorization header; the hosted endpoint is always up-to-date with the latest tool catalog.

Local server

Run the MCP server process on your machine. Useful when you need offline access, custom MIOSA_API_URL overrides, or want to inspect traffic.

# Python
pip install git+https://github.com/Miosa-osa/miosa-mcp.git
miosa-mcp

# TypeScript (no install)
npx @miosa/cli mcp serve

How it works

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

When a client sends initialize, the server returns an instructions field containing a workflow guide - a compact description of MIOSA resource types, lifecycle conventions, and recommended tool patterns. MCP-aware clients like Claude Code surface this to the model at session start, so the agent understands the platform without requiring extra prompting.

Configuration

Claude Code

Add to ~/.claude/mcp.json:

Cursor

Open Cursor → Settings → MCP and add:

Windsurf

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

Reload Windsurf. Tools are available in the Cascade panel.

Environment variable reference (local server only)

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 (145 tools)

Computer lifecycle (8 tools)

Tool	Description
`computer_create`	Boot a Linux desktop VM. Accepts `template`, `size`, `name`.
`computer_list`	List computers. Filterable by `workspace_id`, `status`.
`computer_get`	Get computer status, IP, template, region.
`computer_update`	Update computer name or configuration.
`computer_destroy`	Permanently delete a computer.
`computer_start`	Start a stopped computer.
`computer_stop`	Stop a running computer.
`computer_restart`	Restart a running computer.

Desktop control (30 tools)

Tool	Description
`desktop_screenshot`	Take a full-screen screenshot. Returns base64 PNG.
`desktop_click`	Left-click at coordinates.
`desktop_right_click`	Right-click at coordinates.
`desktop_double_click`	Double-click at coordinates.
`desktop_type`	Type text (Unicode supported).
`desktop_key`	Send a key or chord, e.g. `ctrl+c`.
`desktop_hotkey`	Send a multi-key hotkey.
`desktop_key_down`	Hold a key down.
`desktop_key_up`	Release a held key.
`desktop_scroll`	Scroll at a position: `direction`, `amount`.
`desktop_drag`	Click-drag from start to end coordinates.
`desktop_move_cursor`	Move the mouse cursor without clicking.
`desktop_mouse_down`	Press and hold a mouse button.
`desktop_mouse_up`	Release a mouse button.
`desktop_wait`	Pause execution for N seconds.
`desktop_list_windows`	List open windows with IDs, titles, positions.
`desktop_launch`	Open a named application.
`desktop_focus_window`	Bring a window to the front.
`desktop_set_window_size`	Resize a window to specific dimensions.
`desktop_set_window_position`	Move a window to specific coordinates.
`desktop_maximize_window`	Maximize a window.
`desktop_minimize_window`	Minimize a window to the taskbar.
`desktop_close_window`	Close a window by ID.
`desktop_get_screen_size`	Get display dimensions.
`desktop_get_cursor_position`	Get current cursor position.
`desktop_get_clipboard`	Read clipboard contents.
`desktop_set_clipboard`	Write text to clipboard.
`desktop_get_desktop_env`	Get display, session type, user, desktop environment.
`desktop_set_wallpaper`	Set desktop wallpaper from a URL (white-label branding).
`desktop_accessibility_tree`	Get the AT-SPI accessibility tree for element detection.

File I/O (9 tools)

Tool	Description
`file_bash`	Run a shell command on a computer or sandbox. Returns `stdout`, `stderr`, `exit_code`.
`file_write`	Write a file at an absolute path. Creates parent directories.
`file_read`	Read a file. Returns content as string.
`file_list`	List directory contents. Accepts `recursive` flag.
`file_stat`	Get file metadata (size, permissions, mtime).
`file_mkdir`	Create a directory.
`file_rename`	Rename or move a file.
`file_copy`	Copy a file.
`file_delete`	Delete a file or directory.

Checkpoints (4 tools)

Tool	Description
`checkpoint_create`	Snapshot the current computer or sandbox state.
`checkpoint_list`	List checkpoints for a resource.
`checkpoint_restore`	Restore to a named checkpoint.
`checkpoint_delete`	Delete a checkpoint.

Services (7 tools)

Tool	Description
`service_create`	Create a long-running service on a computer.
`service_list`	List services attached to a computer.
`service_start`	Start a stopped service.
`service_stop`	Stop a running service.
`service_restart`	Restart a service.
`service_logs`	Stream log output for a service.
`service_delete`	Delete a service.

Env / Logs / Domains (7 tools)

Tool	Description
`env_list`	List environment variables for a computer or sandbox.
`env_set`	Create or update an environment variable.
`env_delete`	Delete an environment variable.
`logs_tail`	Stream recent log lines for a computer, sandbox, or deployment.
`domain_add`	Attach a custom domain to a deployment or computer.
`domain_list`	List domains attached to a resource.
`domain_delete`	Remove a custom domain.

Sandbox (20 tools)

Tool	Description
`sandbox_create`	Boot a new sandbox. Accepts `template`, `external_workspace_id`, `external_project_id`.
`sandbox_list`	List sandboxes. Filterable by `external_workspace_id`, `status`.
`sandbox_get`	Get sandbox status, IP, template, created_at.
`sandbox_exec`	Run a shell command. Returns `stdout`, `stderr`, `exit_code`.
`sandbox_destroy`	Permanently destroy a sandbox and release compute.
`sandbox_pause`	Pause a running sandbox (VM paused, not destroyed).
`sandbox_resume`	Resume a paused sandbox from its last state.
`sandbox_python`	Execute a Python snippet directly in the sandbox.
`sandbox_write_file`	Write a file scoped to sandbox paths.
`sandbox_read_file`	Read a file scoped to sandbox paths.
`sandbox_list_files`	List sandbox directory contents.
`sandbox_upload`	Upload a local file into the sandbox.
`sandbox_snapshot_create`	Snapshot the current sandbox state.
`sandbox_snapshot_list`	List snapshots for the sandbox.
`sandbox_snapshot_restore`	Restore a sandbox to a named snapshot.
`sandbox_logs`	Stream sandbox log output.
`sandbox_expose`	Expose a sandbox port as a public HTTPS URL.
`sandbox_deploy`	Deploy sandbox output to a permanent URL.
`sandbox_template_list`	List available sandbox templates.
`sandbox_template_create`	Create a custom sandbox template.

Deployments (11 tools)

Tool	Description
`deployment_list`	List all deployments. Filterable by `status`, `name`.
`deployment_get`	Get deployment status and configuration.
`deployment_create`	Create a new deployment.
`deployment_delete`	Delete a deployment.
`deployment_publish`	Publish from a sandbox source to production.
`deployment_rollback`	Roll back to a previous version.
`deployment_env_list`	List environment variables for a deployment.
`deployment_env_set`	Set an environment variable on a deployment.
`deployment_logs`	Stream deployment logs.
`deployment_version_list`	List versions for a deployment.
`deployment_version_promote`	Promote a version to active.

Storage (8 tools)

Tool	Description
`storage_bucket_list`	List all buckets.
`storage_bucket_create`	Create an object storage bucket.
`storage_bucket_delete`	Delete a bucket.
`storage_object_list`	List objects in a bucket, with optional prefix.
`storage_object_upload`	Upload an object to a bucket.
`storage_object_download`	Download an object from a bucket.
`storage_object_delete`	Delete an object.
`storage_presign`	Generate a time-limited signed URL.

Databases (6 tools)

Tool	Description
`database_list`	List all databases.
`database_create`	Provision a managed Postgres instance.
`database_get`	Get database status and connection details.
`database_delete`	Delete a database.
`database_credentials`	Retrieve the connection string.
`database_logs`	Stream database log output.

Workspaces (6 tools)

Tool	Description
`workspace_list`	List all workspaces. Filterable by `status`, `name`.
`workspace_create`	Create a workspace for tenant isolation.
`workspace_get`	Get workspace details.
`workspace_update`	Rename or reconfigure a workspace.
`workspace_stats`	Get resource counts for a workspace.
`workspace_usage`	Get compute usage stats for a workspace.

Cron (6 tools)

Tool	Description
`cron_list`	List all cron jobs.
`cron_create`	Create a scheduled cron job.
`cron_delete`	Delete a cron job.
`cron_pause`	Pause a cron job without deleting it.
`cron_resume`	Resume a paused cron job.
`cron_run_now`	Trigger a cron job immediately.

Volumes (5 tools)

Tool	Description
`volume_list`	List all volumes.
`volume_create`	Create a persistent volume.
`volume_delete`	Delete a volume.
`volume_attach`	Attach a volume to a computer or sandbox.
`volume_detach`	Detach a volume.

Webhooks (4 tools)

Tool	Description
`webhook_list`	List all webhooks.
`webhook_create`	Create a webhook for an event type.
`webhook_delete`	Delete a webhook.
`webhook_test`	Send a test payload to a webhook endpoint.

Functions (4 tools)

Tool	Description
`function_list`	List serverless functions.
`function_create`	Deploy a serverless function.
`function_invoke`	Invoke a function immediately. Returns `"Function deployment is not yet supported via MCP"` if no function is deployed.
`function_delete`	Delete a function.

API Keys (3 tools)

Tool	Description
`api_key_list`	List API keys for the workspace.
`api_key_create`	Create a new API key with optional scopes.
`api_key_delete`	Revoke an API key.

Network (3 tools)

Tool	Description
`network_policy_get`	Get the current network policy for a resource.
`network_policy_set`	Update the network policy (allowlists, egress rules).
`network_policy_reset`	Reset network policy to defaults.

Ports (3 tools)

Tool	Description
`port_expose`	Expose a port on a computer or sandbox as a public HTTPS URL.
`port_list`	List exposed ports for a resource.
`port_preview_url`	Get the public preview URL for an exposed port.

Billing (2 tools)

Tool	Description
`billing_usage`	Get compute usage for a time window.
`billing_plan`	Get current plan details and limits.

Regions (1 tool)

Tool	Description
`region_list`	List available regions and their availability.

Settings (4 tools)

Tool	Description
`settings_get`	Get workspace settings.
`settings_get_branding`	Get branding configuration (logo, colors, domain).
`settings_update_branding`	Update branding configuration.
`settings_compute_pricing`	Get compute pricing for the current plan.

Usage examples

Create a computer and take a screenshot

You: Create a Linux desktop and take a screenshot of whatever is on screen.

The assistant calls computer_create({ template: "miosa-desktop", size: "small" }), waits for it to boot, calls desktop_screenshot(), and describes what it sees. It can then call desktop_click, desktop_type, and desktop_launch to interact.

Deploy a sandbox to production

You: Build the Next.js app in the sandbox and deploy it to a permanent URL.

The assistant calls sandbox_exec({ command: "npm run build" }), confirms exit_code: 0, then calls deployment_publish({ sourceSandboxId: "sbx_...", kind: "static", outputPath: "/workspace/.next/out" }) and returns the live URL.

Set up a cron job

You: Create a cron job that runs a health check script every 5 minutes.

The assistant calls cron_create({ schedule: "*/5 * * * *", command: "bash /workspace/health-check.sh", sandboxId: "sbx_..." }). To trigger it immediately for a smoke test, it calls cron_run_now({ id: "cron_..." }).

Create a database and get credentials

You: Provision a Postgres database and give me the connection string for my app.

The assistant calls database_create({ name: "my-app-db", region: "us-east" }), polls database_get until status is running, then calls database_credentials({ id: "db_..." }) and returns the connection string. It can also call deployment_env_set to inject DATABASE_URL directly into a deployment.

Troubleshooting

401 Unauthorized on hosted MCP - Confirm the Authorization header value starts with Bearer msk_u_ (not just the key alone). Check that the key is active under Dashboard → Settings → API Keys.

MIOSA_API_KEY is not set (local server) - 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 Forbidden - Your key is valid but lacks the required scope. Check API Keys to confirm the key has the scopes needed for the tools you’re calling.

No tools appear in Cursor - Cursor requires the MCP config to be valid JSON. Run node -e "JSON.parse(require('fs').readFileSync('cursor-mcp.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 the scopes your workflow needs. Never use an admin key for editor integrations.
The hosted MCP endpoint and local MCP server both make outbound HTTPS requests only. Neither opens inbound ports.
Resources created through MCP are subject to the same tenant-scoped authorization as direct API calls. The MCP server cannot access another tenant’s resources.