Wassette

A security-oriented runtime that runs WebAssembly Components via MCP

Getting started | FAQ | Documentation | Releases | Contributing | Discord

Why Wassette?

• Convenience: Wassette makes it easy to extend AI agents with new tools, all without ever having to leave the chat window.
• Reusability: Wasm Components are generic and reusable; there is nothing MCP-specific about them.
• Security: Wassette is built on the Wasmtime security sandbox, providing browser-grade isolation of tools.

Architecture

Installation

Quick start: For Linux/macOS, use our one-liner install script:

curl -fsSL https://raw.githubusercontent.com/microsoft/wassette/main/install.sh | bash

For complete installation instructions for all platforms (including Windows, Homebrew, Nix, and more), see our dedicated Installation Guide.

Available installation methods:

• One-liner script for Linux and macOS
• Homebrew for macOS and Linux
• WinGet for Windows
• Nix flakes for reproducible environments
• Docker for containerized deployments
• Manual download from GitHub Releases

Docker Deployment

For enhanced security isolation and reproducible environments, Wassette can run in Docker containers:

# Build the image
docker build -t wassette:latest .

# Run with streamable-http transport (default)
docker run --rm -p 9001:9001 wassette:latest

# Mount components directory
docker run --rm -p 9001:9001 \
  -v ./components:/home/wassette/.local/share/wassette/components:ro \
  wassette:latest

See the Docker deployment guide for detailed documentation on running Wassette in containers, including security best practices, component mounting, and production deployment patterns.

Using Wassette

With Wassette installed, the next step is to register it with your agent of choice. We have a complete complete setup guide for all agents here, including Cursor, Claude Code, and Gemini CLI.

Add the Wassette MCP Server to GitHub Copilot in Visual Studio Code by clicking the Install in VS Code or Install in VS Code Insiders badge below:

Alternatively, you can add the Wassete MCP server to VS Code from the command line using the code command in a bash/zsh or PowerShell terminal:

bash/zsh

code --add-mcp '{"name":"Wassette","command":"wassette","args":["serve","--stdio"]}'

PowerShell

 code --% --add-mcp "{\"name\":\"wassette\",\"command\":\"wassette\",\"args\":[\"serve\",\"--stdio\"]}"

Now that your agent knows about Wassette, we are ready to load Wasm Components. To teach your agent to tell the time, we can ask it to load a time component:

Please load the time component from oci://ghcr.io/yoshuawuyts/time:latest

Now that the time component is loaded, we can ask your agent to tell you the current time:

What is the current time?

The agent will respond with the current time, which is fetched from the time component running in a secure WebAssembly sandbox:

The current time July 31, 2025 at 10:30 AM UTC

Congratulations! You've just run your first Wasm Component and taught your agent how to tell time!

Demo

wassette-in-60-seconds.mp4

Documentation

The Wassette documentation supports multiple versions:

• /latest/ - Built from the main branch (latest development)
• /vX.Y/ - Built from release tags (e.g., v0.3.0)

Use the version dropdown in the docs header to switch between versions while staying on the same page.

Built-in Tools

Wassette comes with several built-in tools for managing components and their permissions. These tools are available immediately when you start the MCP server:

Tool	Description
load-component	Dynamically loads a new tool or component from either the filesystem or OCI registries
unload-component	Unloads a tool or component
list-components	Lists all currently loaded components or tools
search-components	Lists all known components that can be fetched and loaded from the component registry
get-policy	Gets the policy information for a specific component
grant-storage-permission	Grants storage access permission to a component, allowing it to read from and/or write to specific storage locations
grant-network-permission	Grants network access permission to a component, allowing it to make network requests to specific hosts
grant-environment-variable-permission	Grants environment variable access permission to a component, allowing it to access specific environment variables
revoke-storage-permission	Revokes all storage access permissions from a component for the specified URI path, removing both read and write access to that location
revoke-network-permission	Revokes network access permission from a component, removing its ability to make network requests to specific hosts
revoke-environment-variable-permission	Revokes environment variable access permission from a component, removing its ability to access specific environment variables
reset-permission	Resets all permissions for a component, removing all granted permissions and returning it to the default state

Component Management Tools

load-component

Parameters:

• path (string, required): Path to the component from either filesystem or OCI registries (e.g., oci://ghcr.io/yoshuawuyts/time:latest or /path/to/component.wasm)

Returns:

{
  "status": "component loaded successfully",
  "id": "component-unique-id",
  "tools": ["tool-one", "tool-two"]
}

When an existing component is replaced, the status value becomes component reloaded successfully.

unload-component

Parameters:

• id (string, required): Unique identifier of the component to unload

Returns:

{
  "status": "component unloaded successfully",
  "id": "component-unique-id"
}

list-components

Parameters: None

Returns:

{
  "components": [
    {
      "id": "component-id",
      "tools_count": 2,
      "schema": {
        "tools": [...]
      }
    }
  ],
  "total": 1
}

search-components

Parameters: None

Returns:

{
  "status": "Component list found",
  "components": [
    {
      "name": "Weather Server",
      "description": "A weather component written in JavaScript",
      "uri": "oci://ghcr.io/microsoft/get-weather-js:latest"
    },
    {
      "name": "Time Server", 
      "description": "A time server component written in JavaScript",
      "uri": "oci://ghcr.io/microsoft/time-server-js:latest"
    }
  ]
}

Policy Management Tools

get-policy

Parameters:

• component_id (string, required): ID of the component to get policy information for

Returns:

{
  "status": "policy found",
  "component_id": "component-id",
  "policy_info": {
    "policy_id": "policy-uuid",
    "source_uri": "oci://registry.example.com/component:tag",
    "local_path": "/path/to/cached/component",
    "created_at": 1640995200
  }
}

Permission Grant Tools

grant-storage-permission

Parameters:

• component_id (string, required): ID of the component to grant storage permission to
• details (object, required):
  • uri (string, required): URI of the storage resource (e.g., fs:///tmp/test)
  • access (array, required): Array of access types, must be ["read"], ["write"], or ["read", "write"]

Returns:

{
  "status": "permission granted successfully",
  "component_id": "component-id",
  "permission_type": "storage",
  "details": {
    "uri": "fs:///tmp/test",
    "access": ["read", "write"]
  }
}

grant-network-permission

Parameters:

• component_id (string, required): ID of the component to grant network permission to
• details (object, required):
  • host (string, required): Host to grant network access to (e.g., api.example.com)

Returns:

{
  "status": "permission granted successfully",
  "component_id": "component-id",
  "permission_type": "network",
  "details": {
    "host": "api.example.com"
  }
}

grant-environment-variable-permission

Parameters:

• component_id (string, required): ID of the component to grant environment variable permission to
• details (object, required):
  • key (string, required): Environment variable key to grant access to (e.g., API_KEY)

Returns:

{
  "status": "permission granted successfully",
  "component_id": "component-id",
  "permission_type": "environment",
  "details": {
    "key": "API_KEY"
  }
}

Permission Revoke Tools

revoke-storage-permission

Parameters:

• component_id (string, required): ID of the component to revoke storage permission from
• details (object, required):
  • uri (string, required): URI of the storage resource to revoke access from (e.g., fs:///tmp/test)

Returns:

{
  "status": "permission revoked successfully",
  "component_id": "component-id",
  "uri": "fs:///tmp/test",
  "message": "All access (read and write) to the specified URI has been revoked"
}

revoke-network-permission

Parameters:

• component_id (string, required): ID of the component to revoke network permission from
• details (object, required):
  • host (string, required): Host to revoke network access from (e.g., api.example.com)

Returns:

{
  "status": "permission revoked",
  "component_id": "component-id",
  "permission_type": "network",
  "details": {
    "host": "api.example.com"
  }
}

revoke-environment-variable-permission

Parameters:

• component_id (string, required): ID of the component to revoke environment variable permission from
• details (object, required):
  • key (string, required): Environment variable key to revoke access from (e.g., API_KEY)

Returns:

{
  "status": "permission revoked",
  "component_id": "component-id",
  "permission_type": "environment",
  "details": {
    "key": "API_KEY"
  }
}

reset-permission

Parameters:

• component_id (string, required): ID of the component to reset permissions for

Returns:

{
  "status": "permissions reset successfully",
  "component_id": "component-id"
}

These tools enable you to dynamically manage components and their security permissions without needing to restart the server or modify configuration files directly.

Building WebAssembly Components

Wasm Components provide fully typed interfaces defined using WebAssembly Interface Types (WIT). Wassette can take any Wasm Component and load it as an MCP tool by inspecting the types it exposes. Take for example the following WIT definition for a time server:

package local:time-server;

world time-server {
    export get-current-time: func() -> string;
}

You'll notice that this interface doesn't mention MCP at all; it is just a regular library interface that exports a function. That means there is no such thing as a "Wassette-specific Wasm Component". Wassette is able to load any Wasm Component and expose its functions as MCP tools. Components can be re-used by other Wasm runtimes.

See the examples/ directory for a complete list of examples. Here is a selection of examples written in different languages:

Example	Description
brave-search-rs	Web search using Brave Search API
context7-rs	Search libraries and fetch documentation via Context7 API
eval-py	Python code execution sandbox
fetch-rs	HTTP API client for fetching and converting web content
filesystem-rs	File system operations (read, write, list directories)
get-open-meteo-weather-js	Weather data via Open-Meteo API (no API key required)
get-weather-js	Weather API client using OpenWeather API
gomodule-go	Go module information tool
time-server-js	JavaScript-based time server component

Community Components

The Wassette community has built amazing components that you can use in your projects:

• QR Code Generator - Generate QR codes from text using a WebAssembly component by @attackordie

Discord

You can join us via the #wassette channel on the Microsoft Open Source Discord:

Contributing

Please see CONTRIBUTING.md for more information on how to contribute to this project.

License

This project is licensed under the MIT License.

Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft’s Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party’s policies.

Contributors

Thanks to all contributors who are helping shape Wassette into something great.