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 capability-scoped tool catalog

The hosted MCP exposes MIOSA primitives as MCP tools. The server filters the catalog by the capabilities available to the authenticated account. Call tools/list instead of relying on a hardcoded tool count or static list.

Representative tools include:

Tool family	Examples
Sandboxes	`create_sandbox`, `list_sandboxes`, `exec`, `read_file`, `write_file`, `destroy_sandbox`
Desktops	`create_desktop` and the computer interaction tools returned by `tools/list`
Deployments	`sandbox_deploy_docker`, `deployment_get`, `deployment_publish`, `deployment_rollback`
App Engine	`docker_deploy_host_ensure`, `docker_deploy_doctor`
Domains and configuration	Deployment environment and domain tools returned for the account

Tool names and schemas can evolve additively. Treat the tools/list response as the executable contract.

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 in the Miosa-osa/miosa-skills repository. To install all five at once:

git clone https://github.com/Miosa-osa/miosa-skills.git
cp -r miosa-skills/* ~/.claude/skills/

See the Claude Code Skills page for the current skill catalog and customization guide. Clone or copy the skills directory separately from the MCP connection.

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. Our API key auth layer that protects every REST endpoint also protects the MCP, so the MCP surface inherits all existing guarantees: tenant scoping, plan limits, credit checks, audit logging.

The CLI device-code flow is the supported way to establish credentials without manually copying a key. Clients connecting directly must send a valid bearer key. Do not assume MCP discovery-based OAuth metadata is available unless the server advertises it.

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 sandbox is prepared. Poll list_sandboxes until status=running; readiness time depends on current catalog readiness and available capacity. If it never reaches running, 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.