mcp-server-template

Template repository for creating a WebAssembly component Model Context Protocol (MCP) Server, with wasmCloud.

Dependencies

• Download wash

Quickstart

Clone this repository or use wash to create a new project that uses this repo as a template:

wash new mcpserver --git https://github.com/cosmonic-labs/mcp-server-template-ts.git

cd mcpserver

Start the development loop

Build the component:

npm install
npm run dev

To debug your component, we recommend using the official MCP model inspector, to run that you can run:

npm run inspector

Using the model inspector you can connect to the local MCP server via HTTP, manipulate resources, run tools, and more.

Optional: Generate MCP tools with the openapi2mcp plugin

The openapi2mcp plugin for wash enables you to generate MCP tools from an OpenAPI specification.

Install the plugin:

wash plugin install ghcr.io/cosmonic-labs/openapi2mcp:v0.5.0

Generate MCP tools into the server project from an OpenAPI specification:

wash openapi2mcp [path/to/open/yaml/or/json] --project-path [path/to/generated/mcp/server]

Set up Cosmonic Control

Once your MCP server is ready for primetime, ensure your Cosmonic cluster is running.

Don't have a Comsonic cluster set up?

:::warning[Cosmonic Control required] You will need a Kubernetes cluster and an installation of Cosmonic Control to deploy the component. Sign-up for Cosmonic Control's free trial and follow the Get Started instructions in the Cosmonic Control documentation. :::

Requirements:

• kubectl
• Helm v3.8.0+

Install local Kubernetes environment

For the best local Kubernetes development experience, we recommend installing kind with the following kind-config.yaml configuration:

kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
# One control plane node and three "workers."
nodes:
- role: control-plane
  extraPortMappings:
  - containerPort: 30950
    hostPort: 80
    protocol: TCP

This will help enable simple local ingress with Envoy.

Start the cluster:

kind create cluster --config=kind-config.yaml

Install Cosmonic Control

:::warning[License key required] You'll need a trial license key to follow these instructions. Sign up for Cosmonic Control's free trial to get a key. :::

Deploy Cosmonic Control to Kubernetes with Helm:

helm install cosmonic-control oci://ghcr.io/cosmonic/cosmonic-control\
  --version 0.3.0\
  --namespace cosmonic-system\
  --create-namespace\
  --set envoy.service.type=NodePort\
  --set envoy.service.httpNodePort=30950\
  --set cosmonicLicenseKey="<insert license here>"

Deploy a HostGroup:

helm install hostgroup oci://ghcr.io/cosmonic/cosmonic-control-hostgroup --version 0.3.0 --namespace cosmonic-system

Deploy the application with Helm CLI

Make sure to substitute your own pushed image in the command below:

helm install cosmonic-control oci://ghcr.io/cosmonic-labs/charts/http-trigger\
  --version 0.1.2\
  --set components.name=mcpserver\
  --set components.image=ghcr.io/cosmonic-labs/petstore-mcp-server:v0.2.0\
  --set ingress.host="mcpserver.localhost.cosmonic.sh"\
  --set pathNote="/v1/mcp"

Connect to the deployed MCP server

You can use the official MCP model inspector to connect. Start the MCP inspector via the following command:

npx @modelcontextprotocol/inspector