API Reference

Core Types

WebMCPToolDefinition

Defines a tool that can be registered with a WebMCP server.

interface WebMCPToolDefinition {
  name: string;
  description: string;
  inputSchema: {
    type: 'object';
    properties?: Record<string, any>;
    required?: string[];
  };
}

WebMCPToolHandler

Function that executes when a tool is called.

type WebMCPToolHandler = (args: Record<string, any>) => Promise<any> | any;

WebMCPTransport

Abstract transport interface for all communication channels.

interface WebMCPTransport {
  connect(): Promise<void>;
  disconnect(): Promise<void>;
  send(message: WebMCPMessage): Promise<void>;
  onMessage(handler: (message: WebMCPMessage) => void): void;
  onConnect?(handler: () => void): void;
  onDisconnect?(handler: () => void): void;
  isConnected(): boolean;
}

WebMCPRequest

JSON-RPC 2.0 request message.

interface WebMCPRequest {
  jsonrpc: '2.0';
  id: string | number;
  method: string;
  params?: Record<string, any>;
}

WebMCPResponse

JSON-RPC 2.0 response message.

interface WebMCPResponse {
  jsonrpc: '2.0';
  id: string | number;
  result?: any;
  error?: {
    code: number;
    message: string;
    data?: any;
  };
}

---

Classes

WebMCPClient

Agent-side client for discovering and calling tools.

import { WebMCPClient } from '@thestudioxi/webmcp';

const client = new WebMCPClient({
  transport: myTransport,
  timeoutMs: 10000,
});

Method	Signature	Description
connect	() => Promise<void>	Open transport connection
disconnect	() => Promise<void>	Close transport connection
listTools	() => Promise<WebMCPToolDefinition[]>	List all registered tools
callTool	(name: string, args?: Record<string, any>) => Promise<any>	Execute a tool

---

WebMCPServer

Tool host and JSON-RPC dispatcher.

import { WebMCPServer } from '@thestudioxi/webmcp';

const server = new WebMCPServer({ transport: myTransport });

Method	Signature	Description
registerTool	(definition: WebMCPToolDefinition, handler: WebMCPToolHandler) => void	Register a tool
start	() => Promise<void>	Start the server (connects transport)
stop	() => Promise<void>	Stop the server (disconnects transport)

---

WebMCPBrowserBridge

Frontend SDK for browser-side tool hosting.

import { createFrontendBridge } from '@thestudioxi/webmcp';

const bridge = createFrontendBridge({
  transport: myTransport,
  autoRegisterStarterKit: true,
});

Method	Signature	Description
registerTool	(definition, handler) => this	Register a custom tool
registerCustomTool	(name, description, inputSchema, handler) => this	Register with inline args
registerStarterKit	() => this	Register all starter kit tools
start	() => Promise<void>	Start the bridge
stop	() => Promise<void>	Stop the bridge

---

WebMCPAgentClient

Backend SDK for server-side agent integration.

import { createBackendAgentClient } from '@thestudioxi/webmcp';

const agent = createBackendAgentClient({ transport: myTransport });

Method	Signature	Description
connect	() => Promise<void>	Connect to WebMCP server
disconnect	() => Promise<void>	Disconnect
getAvailableTools	() => Promise<WebMCPToolDefinition[]>	List available tools
executeTool	(name: string, args?: Record<string, any>) => Promise<any>	Execute a tool
getVercelAITools	() => Promise<Record<string, VercelAITool>>	Get tools in Vercel AI SDK format
getRawClient	() => WebMCPClient	Access the underlying client

---

Transports

MessageChannelTransport

For in-page communication (iframes, workers, content scripts).

import { MessageChannelTransport } from '@thestudioxi/webmcp';

const { port1, port2 } = new MessageChannel();
const transport = new MessageChannelTransport(port1);

WebSocketTransport

For local network IPC over WebSocket.

import { WebSocketTransport } from '@thestudioxi/webmcp';

const transport = new WebSocketTransport({
  url: 'ws://localhost:8765',  // client mode
  // or
  port: 8765,                  // server mode
  role: 'client' | 'server',
});

WebStandardHttpTransport

For HTTP-based request/response communication.

import { WebStandardHttpTransport } from '@thestudioxi/webmcp';

const transport = new WebStandardHttpTransport({
  corsOrigin: '*',
  requestTimeoutMs: 30000,
});

Method	Signature	Description
handleRequest	(request: Request) => Promise<Response>	Process an HTTP request

createWebMCPHttpHandler(transport)

Helper that returns a fetch-compatible handler:

import { createWebMCPHttpHandler } from '@thestudioxi/webmcp';

const handler = createWebMCPHttpHandler(transport);
// handler: (request: Request) => Promise<Response>

---

Adapter Functions

createExpressWebMCPMiddleware(transport)

Creates Express.js middleware. Returns (req, res, next) => void.

createHonoWebMCPHandler(transport)

Creates a Hono route handler. Returns (c: Context) => Promise<Response>.

WebMCPAdapter

Self-contained adapter for NestJS and other server-side frameworks.

webmcpToVercelAITools(tools, execute?)

Converts WebMCP tool definitions to Vercel AI SDK format.

jsonSchemaObjectToZod(inputSchema)

Converts JSON Schema to Zod schema for Vercel AI SDK compatibility.