MCP Server

MIOSA ships a public Model Context Protocol server at https://api.miosa.ai/api/v1/mcp. Any MCP-aware AI client — Claude Code, Cursor, Gemini CLI, OpenCode, Hermes, custom GPTs — can connect with a single command and immediately gain MIOSA’s sandbox + desktop + deploy toolbelt.

One-command install (recommended)

npx -y @miosa/cli mcp install

What happens:

The CLI starts MIOSA’s device-code flow
Your browser opens to miosa.ai/cli/auth — log in and approve the request
The CLI receives a fresh msk_u_* user key, scoped to your account
It runs claude mcp add for you — your Claude Code is now connected

Verify:

claude mcp list
# miosa  https://api.miosa.ai/api/v1/mcp  ✓ Connected

Open any Claude Code session and ask:

Create a MIOSA sandbox, run python -c "print(2+2)" inside it, then destroy it.

Claude will discover the tools (create_sandbox, exec, destroy_sandbox) and run them against your account.

Install for other clients

What you get — the tool catalogue

The hosted MCP exposes MIOSA primitives as MCP tools. All tools are scoped to your tenant via the bearer token — you only ever see and act on your own resources, with the same plan limits and credit checks as the REST API.

Tool	Purpose
`create_sandbox`	Boot a Debian 12 microVM (Python 3.12 + Node 20).
`create_desktop`	Boot a full Xfce desktop (KasmVNC) for browser/GUI work.
`list_sandboxes`	List your active computers (sandboxes + desktops).
`destroy_sandbox`	Delete a computer.
`exec`	Run a shell command. Returns stdout/stderr/exit_code.
`exec_python`	Run a Python snippet inline.
`read_file`	Read a file from the VM filesystem.
`write_file`	Write a file inside the VM.
`list_files`	`ls` a directory inside the VM.

Surface is expanding — call tools/list to see what’s current.

Drop-in skills for Claude Code

If your client supports Anthropic-style skills (Claude Code does), drop these markdown files into .claude/skills/ to make MCP usage feel native to your agent. Each skill is a single .md file with frontmatter.

Canonical skill files

The skills above live as standalone files in the MIOSA repo at skills/. To install all three at once:

mkdir -p ~/.claude/skills
curl -fsSL https://raw.githubusercontent.com/miosa-ai/miosa/main/skills/miosa-sandbox.md > ~/.claude/skills/miosa-sandbox.md
curl -fsSL https://raw.githubusercontent.com/miosa-ai/miosa/main/skills/miosa-desktop.md > ~/.claude/skills/miosa-desktop.md
curl -fsSL https://raw.githubusercontent.com/miosa-ai/miosa/main/skills/miosa-deploy.md  > ~/.claude/skills/miosa-deploy.md

A miosa mcp install --with-skills flag is coming — until then, copy-paste or curl the files above.

Drop this into a fresh agent

Paste the block below into a fresh Claude Code (or OpenCode / Hermes / Cursor) session. The agent will pick up everything it needs.

You're connected (or about to connect) to MIOSA — a platform that gives
you cloud microVM sandboxes, full Linux desktops, and one-click deploys.

Step 1: If `claude mcp list` does NOT show a 'miosa' server, run:
    npx -y @miosa/cli mcp install

That opens a browser. Ask me (the user) to approve the login. Once the
command finishes, the 'miosa' MCP server is connected.

Step 2: Read https://miosa.ai/docs/mcp end-to-end. The "drop-in skills"
section has three skills (miosa-sandbox, miosa-desktop, miosa-deploy)
that describe how to use the tools properly.

Step 3: From here on, prefer MIOSA sandboxes over your local tools when
the user asks you to RUN code, INSTALL packages, BUILD a project, or
operate a GUI. Use `exec` / `exec_python` / `write_file` / `read_file`
from the 'miosa' MCP.

Step 4: When the user is happy with what you built, deploy it (the
miosa-deploy skill explains how).

If anything fails with HTTP 401, your MCP key has expired — run
`miosa mcp install` again.

Auth model

The hosted MCP today authenticates with any valid msk_u_* user API key in the Authorization: Bearer ... header. The same plug (Web.Plugs.ApiKeyAuth) that protects every REST endpoint protects the MCP, so the MCP surface inherits all existing guarantees: tenant scoping, plan limits, credit checks, audit logging.

Coming soon: MCP-spec OAuth 2.1 + PKCE Dynamic Client Registration, so clients that prefer the discovery flow can connect with zero manual key paste. The 401 challenge will include WWW-Authenticate: Bearer resource_metadata=... pointing at the standard well-known endpoint.

Troubleshooting

Your key is invalid, expired, or revoked. Re-run miosa mcp install to mint a fresh one, or rotate at https://miosa.ai/dashboard/api-keys.

Install Claude Code first: https://claude.com/claude-code. Then re-run miosa mcp install.

create_sandbox returns immediately while the VM boots in the background. Poll list_sandboxes until status=active — usually 2-3s warm, up to 30s cold. If it never reaches active, the workspace may be over plan limits. Check https://miosa.ai/dashboard/plan.

Your plan caps the number of concurrent sandboxes, or the size you can boot. Upgrade at https://miosa.ai/billing, or destroy unused computers with destroy_sandbox.

Hosted HTTP vs local stdio

Mode	When to use
Hosted HTTP (`https://api.miosa.ai/api/v1/mcp`)	Recommended. Works with any modern MCP client. No local install. This is what `miosa mcp install` wires for you.
Local stdio (`miosa mcp serve` or `pip install miosa-mcp`)	Useful when your client doesn’t yet support remote MCP, or you want to wrap the bridge with custom logic. Both modes call the same REST API under the hood.

Both modes are first-class. The hosted path is just easier to share.