cosmonic-mcp
The Model Context Protocol server for Cosmonic Desktop. It lets a coding agent scaffold, build, deploy and observe WebAssembly component workloads in the local sandbox — from "build me an API" to a running URL.
It is a stateless facade over the daemon's /v1 API, reached across the
local unix socket (named pipe on Windows). It opens no network listener and
needs no auth token: the peer-checked socket is the trust boundary.
[Claude Code / Claude Desktop / Codex / Cursor / …]
│ stdio (JSON-RPC 2.0, MCP)
[cosmonic-mcp] ← this crate
│ HTTP/JSON over the unix socket (peer-cred, 0700/0600)
[cosmonicd] ← Cosmonic Desktop's daemon
Install
cosmonic-mcp needs a running Cosmonic Desktop. Register it with any MCP
client as the command — it takes no arguments:
{ "mcpServers": { "cosmonic": { "command": "/path/to/cosmonic-mcp" } } }
$ claude mcp add --scope user cosmonic -- /path/to/cosmonic-mcp
$ codex mcp add cosmonic -- /path/to/cosmonic-mcp
Cosmonic Desktop's Settings → MCP Server writes this for you, per client.
Two binaries, one implementation
This crate builds the standalone cosmonic-mcp binary and backs
cosmonicd mcp serve, which delegates to the same serve(). Neither has its
own copy of a tool, a description, or an annotation — an annotation is what a
client's auto-permission model keys off, and two surfaces that could disagree
about which tools are read-only is a security bug waiting to be written.
Tools
33 tools in ten resource families, named cosmonic_<resource>_<verb> so a
family clusters in an alphabetical tool list. Reads and writes are separate
tools — no tool takes an action selector — and every tool carries a title
plus exactly one of readOnlyHint / destructiveHint.
Reads: host_status, template_list, project_list, workload_list,
workload_get, workload_validate, workload_revision_list,
workload_credentials_test, workload_draft, dev_status, dev_logs,
logs_query, image_inspect, image_list, secret_list, config_list,
registry_list, registry_test. Everything else writes.
Every tool returns a uniform envelope — { status, result, next_steps[], errors[].recovery } — so an agent always knows what to do next and how to
recover.
project_publish, workload_delete, workload_rollback, secret_delete,
project_delete and image_prune additionally require confirm=true.
workload_validate is the rehearsal: it reports what an apply would say —
schema errors, deny-all egress, inert loopback ports, secret references this
host does not have — while storing nothing, pulling nothing and scheduling
nothing.
project_publish schedules nothing. It builds and pushes the component and
returns the digest-pinned image plus a workloadManifest to review; applying
that manifest is what deploys it.
Skills over MCP
The tools are the hands; a skill is the manual. This server publishes the
cosmonic-sandbox skill family through the MCP Skills extension
(io.modelcontextprotocol/skills, MCP 2026-07-28 —
ext-skills), so
connecting is enough — an agent gets the playbook without installing
anything, including agents with no skills directory at all.
Five skills, published flat: cosmonic-sandbox, cosmonic-go,
cosmonic-nats, cosmonic-nats-tuning, cosmonic-kafka.
Disclosure is progressive:
Reading everything is ~300 KB; the catalog is ~6 KB. That gap is the point.
Three channels, one catalog: skills/list, instructions, skill://index.json —
all generated from the same entries.
Skill content is embedded at compile time, so the binary is self-contained,
works air-gapped, and cannot ship a playbook documenting a tool it does not
have. Every lookup matches a URI verbatim against a static table — no
filesystem, so no path traversal — and the manifest digests are computed from
the same embedded bytes resources/read serves. The upstream MCP Inspector's
--method skills/list --verify (the SEP-2640 conformance run) passes clean.
Resources
cosmonic://schema/workload— theruntime.wasmcloud.dev/v1alpha1Workload spec plus a worked HTTP-API example. Read it before authoring a workload.cosmonic://host,cosmonic://workloads,cosmonic://templates— live state, fetched at read time.skill://index.json,skill://<name>/SKILL.md— see above.
Environment
Security
- No new network surface — stdio to the client, a local socket to the daemon.
- Secrets stay references.
cosmonic_set_secretwrites to the OS keychain; values are never returned, logged, or included in an error. A workload whosesecretFromref is missing is accepted and parked, and the result tells the agent what is missing and that the user enters it in Cosmonic Desktop. - Egress is fail-closed — a workload's
allowedHostsis deny-all until set. - Annotations are a control, not metadata. A tool wrongly marked read-only runs without a confirmation prompt, so the crate's tests fail the build on a missing, contradictory, or multiplexed annotation.
- Direct URLs reach less far for an agent than for a person — the daemon refuses cloud instance-metadata endpoints outright, and refuses loopback/private targets for MCP-originated requests.
Build
$ cargo build --release --bin cosmonic-mcp
No cosmonic-host dependency, by design: that would pull the whole
wash-runtime/wasmtime build into a binary meant to stay small enough to ship
inside an MCP Bundle.
License
Apache-2.0. See LICENSE.