wasmer-mcp package icon
wasmer/wasmer-mcp
Public
wasmer run wasmer/wasmer-mcp

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.

VariableDefault
WASMER_MCP_USER_REQUESTS_PER_MINUTE300
WASMER_MCP_SESSION_REQUESTS_PER_MINUTE120
WASMER_MCP_USER_DEPLOYS_PER_HOUR20

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

  1. Check out the release tag and build the module (make wasix). The release workflow only publishes native binaries; Edge deploys come from wasmer deploy.
  2. Create the app secret WASMER_MCP_OAUTH_SECRET (at least 32 random characters) in the Wasmer dashboard under the app's Secrets, or with wasmer app secrets create. Keep it stable: changing it invalidates pending sign-ins. Never put it in app.yaml.
  3. Run wasmer deploy from the repository root as a member of the wasmer namespace. It publishes the package and deploys app.yaml.
  4. Attach the custom domain mcp.wasmer.io in the dashboard (Domains) and point its DNS at Wasmer Edge. Until then the app answers on its *.wasmer.app URL; add that host to WASMER_MCP_ALLOWED_HOSTS to 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

ToolBehavior
get_appInspect an app by ID or owner/name.
app_http_fetchFetch an app path and buffer its response; redirects are returned without following their target.
app_http_fetch_headersRead a buffered response's headers.
app_http_fetch_bodyRead a buffered body or byte range.
list_apps_in_namespaceList a namespace's apps.
list_my_appsList the caller's apps.
get_package_infoInspect package metadata.
get_package_version_infoInspect a specific package version.
list_package_filesList files in a package volume.
get_package_file_contentRead package text or base64 binary content.
list_app_templatesList app templates.
get_app_templateInspect a template by slug.
whoamiReturn the verified caller's current cached username.
app_builder_initCreate a builder, optionally from a template.
app_builder_init_from_appInitialize a builder from an app.
app_builder_list_filesList builder files.
app_builder_read_fileRead a builder file or byte range.
app_builder_write_fileWrite a builder file or byte range.
app_builder_publishUpload source and start a Wasmer autobuild.
deploy_repoBuild and deploy a public Git repository, optionally from a branch and subdirectory.
wait_for_deploymentFollow a started build's status and recent logs.
list_app_env_varsList an app's environment variable names; values are never returned.
set_app_env_varCreate or replace a variable (sensitive by default), optionally redeploying.
delete_app_env_varDelete a variable by name, optionally redeploying.
get_app_logsRead the latest runtime log lines (default 100, max 1,000), optionally filtered by text.
list_app_domainsList an app's domains, verification state and required DNS records.
add_app_domainAttach a custom domain and return the DNS records to create.
remove_app_domainDetach a domain from an app.
delete_appPermanently 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.

Wasmer MCP server (Streamable HTTP transport)


Github