Wasmer MCP server
Inspect Wasmer apps/packages and deploy apps through the Model Context Protocol. The same binary supports local stdio and authenticated remote HTTP.
Local stdio
export WASMER_TOKEN='your-personal-access-token'
cargo run --locked
WASMER_REGISTRY optionally selects another GraphQL endpoint. WASMER_MCP_DATA_DIR
selects persistent builder/cache storage (default ~/.wasmer-mcp). Logs go to stderr
at INFO level; stdout is reserved for MCP. Debug logging can expose tool arguments.
Remote HTTP
cargo run --locked -- --transport http --host 127.0.0.1 --port 3000
Connect to http://127.0.0.1:3000/mcp. Native clients send
Authorization: Bearer <WASMER_TOKEN> on every request. The HTTP server ignores
its own WASMER_TOKEN; it never substitutes a shared credential. /healthz is public.
The protected-resource and authorization-server metadata are under /.well-known/.
Set WASMER_MCP_PUBLIC_URL to the external HTTP(S) origin behind a proxy. Additional
validated Host values use WASMER_MCP_ALLOWED_HOSTS (comma separated); * explicitly
disables host checking. Browser clients from another origin need an explicit
WASMER_MCP_ALLOWED_ORIGINS entry; native clients without Origin remain supported.
Successful token verification is cached for 300 seconds. A revoked token may therefore remain accepted for up to five minutes; downstream registry calls still use the caller's token. Tokens and claim secrets are excluded from debug records.
Request limits and usage events
The HTTP server limits each account and each signed-in client token separately and
answers 429 with Retry-After once a limit is reached. Starting deployments
(app_builder_publish, deploy_repo) has its own hourly limit per account and
returns a tool error instead. Zero disables a limit.
| Variable | Default |
|---|---|
WASMER_MCP_USER_REQUESTS_PER_MINUTE | 300 |
WASMER_MCP_SESSION_REQUESTS_PER_MINUTE | 120 |
WASMER_MCP_USER_DEPLOYS_PER_HOUR | 20 |
Every tool call logs one event with the wasmer_mcp::usage target: tool,
client (the client's self-reported name, else its User-Agent), account_id,
outcome (ok, tool_error, error or rate_limited), error_code and
duration_ms. Arguments, results, tokens and file contents are never logged. Set
WASMER_MCP_LOG_FORMAT=json for one JSON object per line.
Browser sign-in
Deploy frontend-edge #718
before enabling this flow, then verify /auth/claim on the target Wasmer site.
The registry claim mutations already exist; their availability does not prove
that the browser approval page has been deployed. Bearer-token HTTP remains usable
without that page.
Clients discover OAuth metadata, register a return URL and use the authorization code flow with PKCE S256. The browser displays a Wasmer login claim for the user to approve on Wasmer; the server redeems it for the user's personal access token. Codes require the matching client ID, exact return URL and PKCE proof at exchange.
Set WASMER_MCP_OAUTH_SECRET to at least 32 random characters and retain it across
restarts. Without it the process uses a random key and pending sign-ins cannot
survive restart. Used authorization codes leave atomic replay markers in
WASMER_MCP_DATA_DIR/oauth-used-codes; old markers are cleaned after their codes
expire. Instances sharing a key must also share this persistent directory.
There is no claim of storage-free horizontal scaling.
HTTPS client metadata documents are bounded to 64 KiB, resolve only to public addresses and use pinned DNS results, without redirects or environment proxies. For the sign-in UI's shared components and state fixture, see DESIGN.md.
Native HTTP example
WASMER_TOKEN='your-personal-access-token' \
cargo run --locked --example http_client -- http://127.0.0.1:3000/mcp
The example discovers all 29 tools and calls the read-only whoami tool.
Container
docker build -t wasmer-mcp .
# Set WASMER_MCP_OAUTH_SECRET in your shell; never put a real token in the image.
docker run --rm -p 3000:3000 \
-e WASMER_MCP_PUBLIC_URL=http://localhost:3000 \
-e WASMER_MCP_OAUTH_SECRET \
-v wasmer-mcp-data:/data wasmer-mcp
The image runs as UID 10001 and persists state under /data. Make mounted storage
writable to that user. Public deployments need HTTPS at their proxy and the exact
public origin in WASMER_MCP_PUBLIC_URL. The container health check uses /healthz.
Host on Wasmer Edge
The server also builds for WASIX and runs on Wasmer Edge.
wasmer.toml packages the module as wasmer/wasmer-mcp and app.yaml describes
the wasmer/wasmer-mcp app served at https://mcp.wasmer.io.
Build
Install rustup, cargo install cargo-wasix and
wasixcc (it compiles the C code in the
TLS stack), then:
make wasix # CARGO_WASIX_NO_REGISTRY_CONFIG=1 cargo wasix build --release --locked
CARGO_WASIX_NO_REGISTRY_CONFIG=1 stops cargo-wasix from routing all of crates.io
through the WASIX registry, which only offers reqwest 0.12. Instead, Cargo.toml
patches the few crates that need WASIX forks (tokio, mio, socket2, libc, getrandom,
rustls-native-certs) from github.com/wasix-org, and vendor/wasmer-backend-api
carries a one-line cfg fix. The patches also apply to native builds; the forks
keep upstream behavior there. Templates are downloaded as GitHub zip archives, so
the server needs no git binary.
Run locally
mkdir -p /tmp/wasmer-mcp-data
wasmer run . --net --volume /tmp/wasmer-mcp-data:/data \
--env WASMER_TRANSPORT=http --env WASMER_MCP_HOST=0.0.0.0 --env PORT=3000 \
--env WASMER_MCP_DATA_DIR=/data --env WASMER_MCP_PUBLIC_URL=http://localhost:3000 \
--env WASMER_MCP_OAUTH_SECRET="$(openssl rand -hex 32)"
curl http://localhost:3000/healthz
Deploy
- Check out the release tag and build the module (
make wasix). The release workflow only publishes native binaries; Edge deploys come fromwasmer deploy. - Create the app secret
WASMER_MCP_OAUTH_SECRET(at least 32 random characters) in the Wasmer dashboard under the app's Secrets, or withwasmer app secrets create. Keep it stable: changing it invalidates pending sign-ins. Never put it inapp.yaml. - Run
wasmer deployfrom the repository root as a member of thewasmernamespace. It publishes the package and deploysapp.yaml. - Attach the custom domain
mcp.wasmer.ioin the dashboard (Domains) and point its DNS at Wasmer Edge. Until then the app answers on its*.wasmer.appURL; add that host toWASMER_MCP_ALLOWED_HOSTSto test it there.
app.yaml sets WASMER_TRANSPORT=http, WASMER_MCP_HOST=0.0.0.0, PORT=80,
WASMER_MCP_DATA_DIR=/data and WASMER_MCP_PUBLIC_URL=https://mcp.wasmer.io, checks
/healthz, and mounts the persistent volume data at /data. Renaming or removing
that volume deletes its data.
Builders, caches and the OAuth replay markers (/data/oauth-used-codes) live on
that volume. Edge volumes are read-write-many and shared by every instance of the
app in its region, which the replay markers require; if the app ever runs in more
than one region (volumes are single-region today), limit it to a single instance
instead.
Tools
| Tool | Behavior |
|---|---|
get_app | Inspect an app by ID or owner/name. |
app_http_fetch | Fetch an app path and buffer its response; redirects are returned without following their target. |
app_http_fetch_headers | Read a buffered response's headers. |
app_http_fetch_body | Read a buffered body or byte range. |
list_apps_in_namespace | List a namespace's apps. |
list_my_apps | List the caller's apps. |
get_package_info | Inspect package metadata. |
get_package_version_info | Inspect a specific package version. |
list_package_files | List files in a package volume. |
get_package_file_content | Read package text or base64 binary content. |
list_app_templates | List app templates. |
get_app_template | Inspect a template by slug. |
whoami | Return the verified caller's current cached username. |
app_builder_init | Create a builder, optionally from a template. |
app_builder_init_from_app | Initialize a builder from an app. |
app_builder_list_files | List builder files. |
app_builder_read_file | Read a builder file or byte range. |
app_builder_write_file | Write a builder file or byte range. |
app_builder_publish | Upload source and start a Wasmer autobuild. |
deploy_repo | Build and deploy a public Git repository, optionally from a branch and subdirectory. |
wait_for_deployment | Follow a started build's status and recent logs. |
list_app_env_vars | List an app's environment variable names; values are never returned. |
set_app_env_var | Create or replace a variable (sensitive by default), optionally redeploying. |
delete_app_env_var | Delete a variable by name, optionally redeploying. |
get_app_logs | Read the latest runtime log lines (default 100, max 1,000), optionally filtered by text. |
list_app_domains | List an app's domains, verification state and required DNS records. |
add_app_domain | Attach a custom domain and return the DNS records to create. |
remove_app_domain | Detach a domain from an app. |
delete_app | Permanently delete an app; confirm must repeat its exact owner/name. |
Every tool declares MCP tool annotations (a title plus read-only, destructive, idempotent and open-world hints) so clients can tell read-only lookups from changes and ask before publishing or overwriting.
Ownership and resource limits
Builders persist the creator's immutable account ID, so renaming a username does not transfer access. Buffered response headers/bodies use the same identity. Legacy builder records without an immutable creator ID are denied: create a fresh builder rather than adopting unowned state. Cached packages are authorized with the current caller before they are served.
Builder paths reject absolute paths, traversal and symbolic links. Reads, offset writes, the source files and the finished ZIP archive (headers included) are capped at 200 MiB; file names keep any leading or trailing spaces; listings default to 100 entries and at most 1,000. HTTP responses are limited to 10 MiB and 256 retained responses; package inspection downloads stop at 512 MiB even without Content-Length.
Publishing uploads a ZIP through the API and creates or updates the builder's
owner/name; it does not require an installed Wasmer CLI. Results include the build
ID, building/deployed/failed, optional URL and the latest 60 log lines. Waiting
defaults to 50 seconds and is capped at 600; use zero to start without waiting and
call wait_for_deployment later. If the deployment starts but its progress cannot
be read, publishing still returns the build ID as building. deploy_repo returns
the same result for a public https Git repository; URLs with embedded credentials
are rejected. Once a deployment finishes, the live URL is requested up to three times
(five seconds apart, for a cold start) and site reports the HTTP status and whether
it answered with 2xx/3xx. Publishing writes to Wasmer and may incur usage.
Development and verification
cargo fmt --check
cargo check --offline
cargo clippy --offline --all-targets -- -D warnings
cargo test --offline
make ai-setup fetches locked dependencies before offline work. Ordinary tests
use synthetic local APIs. make test-integration explicitly enables ignored tests
that need WASMER_TOKEN; one deploys an app. make review-fixture runs the synthetic
loopback-only UI fixture, and make inspector opens the MCP Inspector. Configure
its WASMER_TOKEN environment variable to inspect a real account.