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 over the daemon's 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.
Model Context Protocol server for Cosmonic Desktop — build, deploy and observe sandboxed WebAssembly workloads on the local host.
Estrelas
1
Ferramentas
—
Disponibilidade
—
stateless facade
/v1
[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:
$ 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.
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.
Method
Returns
skills/list
One Skill entry per skill: uri, verbatim frontmatter, and a complete resources manifest with a sha256: digest and byte size per file
skills/get{uri}
The same entry for one SKILL.md URI; -32602 otherwise
resources/read
Any file in a manifest, skill://<name>/<path>
resources/directory/read{uri}
Direct children of a directory (directoryRead: true is declared)
Disclosure is progressive:
Tier
What
Size
Read when
1
skills/list — or, without the extension, the same catalog in instructions (what a Claude client reads) or the skill://index.json resource
~6 KB
Once, at session start
2
skill://<name>/SKILL.md
14–25 KB
The entry's description matches the task
3
skill://<name>/references/<file>.md
3–26 KB
The playbook points at it
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 — the runtime.wasmcloud.dev/v1alpha1 Workload
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
COSMONIC_SOCKET
Explicit daemon endpoint; wins outright.
COSMONIC_STATE_DIR
The socket is found beside this directory.
COSMONIC_LOG
Log filter (tracing syntax). Logs go to stderr — stdout is the JSON-RPC channel.
Security
No new network surface — stdio to the client, a local socket to the daemon.
Secrets stay references.cosmonic_set_secret writes to the OS keychain;
values are never returned, logged, or included in an error. A workload whose
secretFrom ref 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 allowedHosts is 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.
Ainda não há lista de ferramentas. Servidores remotos recebem uma após a primeira verificação de saúde.
Perguntas frequentes
Perguntas
Como instalo Cosmonic?
Copie nesta página a configuração stdio para Cursor, Claude Desktop, Claude Code ou VS Code. Ela usa a instalação do publicador, não um proxy do PlugMCP.
Cosmonic precisa de uma chave de API?
Este registro não lista nenhuma variável de ambiente obrigatória.
Qual transporte Cosmonic usa?
Cosmonic roda localmente via stdio.
Quando Cosmonic foi verificado pela última vez?
Última verificação: 2026-10-28. Model Context Protocol server for Cosmonic Desktop — build, deploy and observe sandboxed WebAssembly workloads on the local host.