MCP Server for Wippy

A Model Context Protocol server that runs as a Wippy module, communicates over stdio or HTTP, and exposes tools and prompts to LLM clients (Claude Desktop, MCP Inspector, etc.).

Tools and prompts are registry-native — declared as standard Wippy function.lua entries with metadata and discovered automatically. Adding a tool or prompt requires only a YAML entry and (optionally) a Lua handler. No server code changes.

Quick Start

Stdio Transport

wippy run -s -x mcp:server

The -s (silent) flag is required — it suppresses runtime logs so they don't corrupt the JSON-RPC stream.

Test with MCP Inspector:

npx @modelcontextprotocol/inspector wippy run -s -x mcp:server

HTTP Transport

Add the MCP server as a dependency and wire it to your HTTP router:

- name: dep.mcp
  kind: ns.dependency
  component: butschster/mcp-server
  version: "*"
  parameters:
    - name: router
      value: app:api

The MCP endpoint is registered at /mcp on your router (e.g., /api/mcp if your router has prefix: /api).

See HTTP Transport docs for session lifecycle and curl examples.

Adding Tools

Create a Lua handler and register it in _index.yaml:

-- tools/greet.lua
local function call(arguments)
    local name = arguments.name or "World"
    return "Hello, " .. name .. "!"
end

return { call = call }

- name: greet
  kind: function.lua
  source: file://tools/greet.lua
  method: call
  meta:
    mcp.tool: true
    mcp.name: "greet"
    mcp.description: "Greet someone by name"
    mcp.inputSchema:
      type: "object"
      properties:
        name:
          type: "string"
          description: "Name to greet"
      required:
        - "name"

See Tools docs for metadata reference, annotations, error handling, and using Wippy modules.

Adding Prompts

Prompts support three modes: static (YAML messages), dynamic (Lua handler), and template inheritance.

- name: greeting
  kind: function.lua
  source: file://prompts/static.lua
  method: get
  meta:
    mcp.prompt: true
    mcp.prompt.name: "greeting"
    mcp.prompt.description: "Generate a personalized greeting"
    mcp.prompt.arguments:
      - name: "name"
        description: "Name of the person to greet"
        required: true
    mcp.prompt.messages:
      - role: "user"
        content: "Please greet {{name}}."

See Prompts docs for dynamic prompts, template inheritance, and metadata reference.

Supported MCP Methods

Method	Type	Description
initialize	request	Handshake, returns server capabilities
notifications/initialized	notification	Client confirms initialization
ping	request	Health check, returns {}
tools/list	request	List all discovered tools
tools/call	request	Invoke a tool by name
prompts/list	request	List all discovered prompts
prompts/get	request	Get prompt messages by name

Documentation

Document	Description
Stdio Transport	Running via stdio, Claude Desktop configuration
HTTP Transport	Session lifecycle, host app setup, curl examples
Tools	Creating tools, metadata reference, error handling
Prompts	Static, dynamic, and template prompts
Scope Filtering	Multi-endpoint visibility control
Architecture	Module design, dispatch chain, dependency graph

Examples

Example	Description
Basic Tools	Minimal app with three simple tools
HTTP App	HTTP server with MCP endpoint
Multi-Endpoint	Admin vs. public tools with scope filtering
Prompts App	Static, dynamic, and template prompts

Protocol Details

• MCP version: 2025-06-18
• Transports: stdio (newline-delimited JSON), HTTP (Streamable HTTP)
• Capabilities: tools and prompts (both with listChanged: false)