Skip to content
Back to search

wasmcp

Build MCP servers with WebAssembly components

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/wasmcp--wasmcp/badge.svg)](/listings/wasmcp--wasmcp)

HTML

<a href="/listings/wasmcp--wasmcp"><img src="/api/listings/wasmcp--wasmcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

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

See [releases](https://github.com/wasmcp/wasmcp/releases) for SBOMs etc.

Or build from source:

cargo install --git https://github.com/wasmcp/wasmcp

Requires [`wasmtime`](https://wasmtime.dev/), [`wash`](https://github.com/wasmCloud/wash), [`spin`](https://github.com/spinframework/spin), or another component-capable runtime to run composed servers.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 273 lines · 1 finding marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. # `wasmcp`
  3. A [WebAssembly Component](https://component-model.bytecodealliance.org/) Development Kit for the [Model Context Protocol](https://modelcontextprotocol.io/docs/getting-started/intro)
  4. </div>
  5. ## Install
  6. ```bash
  7. curl -fsSL https://raw.githubusercontent.com/wasmcp/wasmcp/main/install.sh | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 12 on GitHub
  8. ```
  9. See [releases](https://github.com/wasmcp/wasmcp/releases) for SBOMs etc.
  10. Or build from source:
  11. ```bash
  12. cargo install --git https://github.com/wasmcp/wasmcp
  13. ```
  14. Requires [`wasmtime`](https://wasmtime.dev/), [`wash`](https://github.com/wasmCloud/wash), [`spin`](https://github.com/spinframework/spin), or another component-capable runtime to run composed servers.
  15. ## Quick Start
  16. Create and run your first MCP tool component:
  17. ```bash
  18. # Create a component in your favorite language
  19. wasmcp new time-tools --language python
  20. cd time-tools && make && cd ..
  21. # Register it with a short alias
  22. wasmcp registry component add time time-tools/time-tools.wasm
  23. # Compose into an MCP server and run
  24. wasmcp compose server time --runtime wasmtime -o server.wasm
  25. wasmtime serve -Scli -Skeyvalue -Shttp server.wasm # http://0.0.0.0:8080/mcp
  26. ```
  27. Combine multiple tool components - they automatically merge into a unified catalog:
  28. ```bash
  29. # Create another component
  30. wasmcp new math-tools --language rust
  31. cd math-tools && make && cd ..
  32. wasmcp registry component add math math-tools/target/wasm32-wasip2/release/math_tools.wasm
  33. # Compose both together
  34. wasmcp compose server time math --runtime wasmtime -o combined-server.wasm
  35. wasmtime serve -Scli -Skeyvalue -Shttp combined-server.wasm
  36. ```
  37. See [examples/](examples/) for more.
  38. ## Documentation
  39. - **[Examples](examples/)**
  40. - **[CLI Reference](cli/README.md)**
  41. - **[Development MCP server](docs/daemon-management.md)** - Run a local development server that provides context to your coding agent about developing, composing, and running `wasmcp` projects.
  42. ## Authentication Modes
  43. wasmcp supports both public (unauthenticated) and OAuth 2.1 protected MCP servers via the `WASMCP_AUTH_MODE` environment variable.
  44. ### Public Mode (Default)
  45. ```bash
  46. # No environment variables needed (default behavior)
  47. wasmtime serve -Scli -Skeyvalue -Shttp server.wasm
  48. ```
  49. Or explicitly set:
  50. ```bash
  51. WASMCP_AUTH_MODE=public wasmtime serve -Scli -Skeyvalue -Shttp server.wasm
  52. ```
  53. ### OAuth Mode
  54. Requires JWT bearer tokens per MCP OAuth 2.1 spec. Supports two validation patterns:
  55. #### Dynamic Registration Pattern
  56. Per-user client IDs created dynamically. No fixed audience - validation via issuer and signature only.
  57. **Required Environment Variables:**
  58. - `WASMCP_AUTH_MODE=oauth` - Enable OAuth authentication
  59. - `JWT_ISSUER` - Expected token issuer (e.g., `https://your.issuer.com`)
  60. - `JWT_JWKS_URI` - JWKS endpoint for public key retrieval
  61. **Example:**
  62. ```bash
  63. WASMCP_AUTH_MODE=oauth \
  64. JWT_ISSUER=https://api.workos.com \
  65. JWT_JWKS_URI=https://api.workos.com/sso/jwks/client_01234567890 \
  66. wasmtime serve -Scli -Skeyvalue -Shttp server.wasm
  67. ```
  68. ## Features
  69. - **Stateful Sessions** - Built-in session management with key-value storage for multi-request workflows
  70. - **Authentication** - JWT/OAuth bearer token validation with scope-based authorization
  71. - **Auto-Composition** - Automatically wraps components with appropriate middleware
  72. - **Type-Safe Storage** - TypedValue enum for runtime type safety in sessions
  73. - **Real-time Notifications** - Progress updates, logs, and resource changes via streaming
  74. ## Why?
  75. WebAssembly components are:
  76. - **Composable** - Combine compiled binaries like building blocks
  77. - **Sandboxed** - Isolated execution with explicit interfaces
  78. - **Distributable** - Push/pull components from OCI registries
  79. - **Lean** - Complete servers can be under 1MB
  80. These qualities are a perfect match for MCP's [server design principals](https://modelcontextprotocol.io/specification/2025-06-18/architecture#design-principles).
  81. > 1. Servers should be extremely easy to build
  82. > 2. Servers should be highly composable
  83. > 3. Servers should not be able to read the whole conversation, nor “see into” other servers
  84. > 4. Features can be added to servers and clients progressively
  85. ## Architecture
  86. Server features like tools, resources, prompts, and completions, are implemented by individual WebAssembly components that export the narrow, spec-mapped WIT interfaces defined in [spec/2025-06-18/wit/](spec/2025-06-18/wit/).
  87. `wasmcp compose` wraps these components with published middleware components from [crates/](crates/) and composes them together behind a transport component as a complete middleware [chain of responsibility](https://en.wikipedia.org/wiki/Chain-of-responsibility_pattern) that implements an MCP server. The chain terminates with [crates/method-not-found](crates/method-not-found), which returns errors for unhandled methods.
  88. Any of the published default wasmcp components can be swapped out for custom implementations during composition, enabling flexible server configurations.
  89. ```
  90. Transport<Protocol>
  91. ↓
  92. Middleware₀
  93. ↓
  94. Middleware<Feature>₁
  95. ↓
  96. Middleware<Feature>₂
  97. ↓
  98. ...
  99. ↓
  100. Middlewareₙ
  101. ↓
  102. MethodNotFound
  103. ```
  104. Each component:
  105. - Handles requests it understands (e.g., `tools/call`)
  106. - Delegates others downstream
  107. - Merges results (e.g., combining tool lists)
  108. This enables dynamic composition without complex configuration - like Unix pipes for MCP.
  109. ### Example Composition
  110. Components can be specified as local paths, registry packages (OCI), aliases, or profiles:
  111. ```bash
  112. # Local file path
  113. wasmcp compose server ./calculator.wasm -o server.wasm
  114. # Registry package (OCI) - colon identifies it as a registry spec
  115. wasmcp compose server wasmcp:calculator@0.1.0 -o server.wasm
  116. # Aliases (registered in ~/.config/wasmcp/wasmcp.toml)
  117. wasmcp compose server calc weather -o server.wasm
  118. # Mixed: local path + registry package + alias
  119. wasmcp compose server ./logger.wasm wasmcp:calculator@1.0 weather -o server.wasm
  120. ```
  121. When a client requests `tools/list`, each component that offers tools contributes their tools, creating a unified catalog automatically.
  122. ## Registry
  123. `wasmcp registry` allows for simple artifact aliases and reusable composition profiles.
  124. ### Component Aliases
  125. Register short names for frequently-used components:
  126. ```bash
  127. # Register local components (file paths)
  128. wasmcp registry component add calc ./calculator.wasm
  129. wasmcp registry component add weather ./weather-tools.wasm
  130. # Register from OCI registry (namespace:name@version)
  131. wasmcp registry component add db wasmcp:database@1.0.0
  132. wasmcp registry component add logger namespace:logger@2.0.0
  133. # Aliases can also reference other aliases
  134. wasmcp registry component add prod-calc calc
  135. # Use aliases in composition
  136. wasmcp compose server calc weather -o server.wasm
  137. wasmcp compose server db logger -o server.wasm
  138. # List and manage
  139. wasmcp registry component list
  140. wasmcp registry component remove calc
  141. ```
  142. ### Profiles
  143. Save a list of components to compose together:
  144. ```bash
  145. # Save: dev = calc + weather
  146. wasmcp registry profile add dev calc weather -o dev.wasm
  147. # Later, rebuild the same server
  148. wasmcp compose server dev
  149. # Creates: ~/.config/wasmcp/composed/dev.wasm
  150. # Or specify a different output location
  151. wasmcp compose server dev -o ./my-server.wasm
  152. # Creates: ./my-server.wasm
  153. ```
  154. Profiles can inherit from other profiles:
  155. ```bash
  156. wasmcp registry profile add prod logger monitor -o prod.wasm -b dev
  157. # prod = calc + weather + logger + monitor
  158. ```
  159. List and remove:
  160. ```bash
  161. wasmcp registry profile list
  162. wasmcp registry profile remove dev
  163. ```
  164. ### Registry Info
  165. View your registry configuration:
  166. ```bash
  167. wasmcp registry info # Show all
  168. wasmcp registry info --components # Filter to components
  169. wasmcp registry info --profiles # Filter to profiles
  170. ```
  171. ### Configuration
  172. Registry data is stored in `~/.config/wasmcp/config.toml` ([XDG Base Directory](https://specifications.freedesktop.org/basedir-spec/latest/)).
  173. ## Components
  174. ### Your Components
  175. Write handlers in any language with [component toolchain support](https://component-model.bytecodealliance.org/language-support.html):
  176. ```bash
  177. wasmcp new my-handler --language rust # Rust (calculator example)
  178. wasmcp new my-handler --language python # Python (string tools example)
  179. wasmcp new my-handler --language typescript # TypeScript (example tool)
  180. ```
  181. Generated templates demonstrate the capability pattern with working tool implementations.
  182. ### Framework Components
  183. Published to [ghcr.io/wasmcp](https://github.com/orgs/wasmcp/packages):
  184. - **transport** - Universal transport for HTTP / stdio execution with JWT validation
  185. - **server-io** - Universal MCP message I/O with configurable transport framing support
  186. - **session-store** - Stateful session management with key-value storage
  187. - **authorization** - JWT/OAuth bearer token validation and claim extraction
  188. - **kv-store** - Type-safe key-value storage with TypedValue support
  189. - **method-not-found** - Terminal handler for unhandled methods
  190. The CLI automatically downloads these when composing.
  191. ## License
  192. Apache 2.0

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.