Modulewise Toolbelt

A Model Context Protocol (MCP) Server that exposes Wasm Components as Tools.

This is currently an early-stage non-production prototype.

Build

Prerequisite: a current rust toolchain

Clone the toolbelt project if you have not already.

Then from within the toolbelt directory:

cargo install --path .

That will build the binary with the release profile and add it to your cargo bin directory which should be on your PATH.

Run Simple Components

Provide the path to one or more .wasm files as command line arguments:

toolbelt hello.wasm calculator.wasm

Or you can specify OCI URIs for published Wasm Components, such as these:

toolbelt oci://ghcr.io/modulewise/demo/hello:0.2.0 \
         oci://ghcr.io/modulewise/demo/calculator:0.2.0

[!TIP]

If you'd like to build the Wasm Components locally, clone the modulewise/demos project and follow the build instructions in components/README.md

Run Components with Dependencies

By default, components operate in a least-privilege capability mode. If your component requires capabilities from the host runtime, you can specify those capabilities in a .toml file:

[capability.http]
type = "wasi:http"

And then define the tool component that imports one or more capabilities:

[component.flights]
uri = "file:///path/to/flight-search.wasm"
imports = ["http"]

Pass the definition file to the server instead of direct .wasm files:

toolbelt flights.toml

Wasm Components can also import other components which may have their own dependencies:

components.toml

[component.incrementor]
uri = "../demos/components/lib/incrementor.wasm"
imports = ["keyvalue"]

[component.incrementor.config]
bucket = "increments"

[component.keyvalue]
uri = "../demos/components/lib/valkey-client.wasm"
imports = ["wasip2"]

And responsibilities can be separated across multiple files:

capabilities.toml

[capability.wasip2]
type = "wasi:p2"

Now these files can be passed to the server:

toolbelt components.toml capabilities.toml

This allows for various combinations of host capabilities and guest components. It also promotes responsibility-driven separation of concerns between supporting infrastructure and domain-centric tools.

Configure the MCP Server

When no [server] with type = "mcp" is configured, toolbelt starts a default MCP server on 127.0.0.1:3001 that auto-discovers top-level components (those not imported by other components).

For explicit control, add a [server] section with type = "mcp" to your definition file.

Discover components to expose as tools with a selector

Use component-selector to match components by metadata:

[server.mcp]
type = "mcp"
port = 3001
component-selector = "!dependents"

This exposes all top-level components as tools. Other selector expressions are supported, for example labels.domain = "shopping" or name = "greeter".

Define tools explicitly

Use [server.mcp.tool.*] entries to map specific component functions to named tools:

[server.mcp]
type = "mcp"
port = 3001

[server.mcp.tool.greeter]
component = "greeter"
function = "greet"
description = "Greet someone by name"

[server.mcp.tool.adder]
component = "calculator"
function = "operations.add"

The tool name comes from the TOML key (greeter and adder above). The function should be qualified by interface if the specified function is exported via interface, or directly if exported at the WIT world level. The description field is optional but plays an important role in providing instructions to a calling agent.

Combine both

Selectors and explicit tools can be used together. Explicit tool definitions take precedence on name collisions:

[server.mcp]
type = "mcp"
port = 3001
component-selector = "!dependents"

[server.mcp.tool.greeter]
component = "greeter"
function = " greet"
description = "Custom description for the greet tool"

Origin validation

Toolbelt validates the Origin header if present on requests per the MCP spec. When binding to a loopback address, localhost origins are allowed by default. Otherwise, all origins are denied unless explicitly configured:

[server.mcp]
type = "mcp"
port = 3001
host = "0.0.0.0"
allowed-origins = ["app.example.com", "localhost"]

OpenTelemetry tracing

Add otlp-endpoint to export spans via OTLP:

[server.mcp]
type = "mcp"
port = 3001
otlp-endpoint = "http://localhost:4317"
otlp-protocol = "grpc"  # or "http/protobuf"; defaults to "grpc"

Spans are emitted for tools/list and tools/call with attributes following the gen_ai MCP semantic conventions. Trace context propagates from client to server via _meta in request params and from server into Wasm component invocations via traceparent in the propagation context.

See examples/otel for a complete example with Jaeger.

Test with MCP Inspector

1. Run the server as described above.

2. Start the MCP Inspector.

3. Ensure the Streamable HTTP Transport Type is selected.

4. Ensure the specified URL is http://127.0.0.1:3001/mcp (replace host or port if not using defaults).

5. Click Connect and then List Tools.

6. Select a Tool, provide parameter values, and click Run Tool.

License

Copyright (c) 2026 Modulewise Inc and the Modulewise Toolbelt contributors.

Apache License v2.0: see LICENSE for details.