MCP server

The MIOSA MCP (Model Context Protocol) server exposes a live, capability-scoped tool catalog. AI coding assistants can create sandboxes, run commands, write files, take computer screenshots, and manage deployments, storage, databases, and other authorized resources without leaving the editor. The server speaks the MCP transport protocol, so any compliant client can drive it.

The exact tool list depends on the authenticated caller, server release, and enabled capabilities. Use MCP tools/list as the authoritative catalog instead of relying on a hardcoded count.

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`

Live tool catalog

Computer lifecycle

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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.