MCP-Web Bridge API

MCPWebBridge

Class — packages/bridge/src/core.ts

Core bridge server that connects web frontends to AI agents via MCP.

MCPWebBridge manages WebSocket connections from frontends, routes tool calls, handles queries, and exposes an HTTP API for MCP clients. It is runtime-agnostic and delegates I/O operations to adapters.

Properties:

MCP_SESSION_IDLE_TIMEOUT_MS: any

Accessors:

get config(): MCPWebConfigOutput

The validated bridge configuration.

Methods:

getHandlers(): BridgeHandlers

Returns handlers for wiring to runtime-specific I/O.

Use these handlers to connect the bridge to your runtime's WebSocket and HTTP servers. Pre-built adapters (Node, Bun, Deno, PartyKit) handle this automatically.

close(): Promise<void>

Gracefully shuts down the bridge.

Closes all WebSocket connections, cancels scheduled tasks, and clears all internal state. Call this when shutting down your server.

AuthenticateMessage

Interface — packages/bridge/src/types.ts

Properties:

type: 'authenticate'

sessionId: string

authToken: string

origin: string

pageTitle?: string

sessionName?: string

userAgent?: string

timestamp: number

AuthenticatedMessage

Interface — packages/bridge/src/types.ts

Properties:

type: 'authenticated'

mcpPort?: number

sessionId: string

success: boolean

AuthenticationFailedMessage

Interface — packages/bridge/src/types.ts

Properties:

type: 'authentication-failed'

error: string

code: string

RegisterToolMessage

Interface — packages/bridge/src/types.ts

Properties:

type: 'register-tool'

tool: {
    name: string;
    description: string;
    inputSchema?: z.core.JSONSchema.JSONSchema;
    outputSchema?: z.core.JSONSchema.JSONSchema;
    _meta?: Record<string, unknown>;
  }

RegisterResourceMessage

Interface — packages/bridge/src/types.ts

Properties:

type: 'register-resource'

resource: ResourceMetadata

ResourceReadMessage

Interface — packages/bridge/src/types.ts

Properties:

type: 'resource-read'

requestId: string

uri: string

ResourceResponseMessage

Interface — packages/bridge/src/types.ts

Properties:

type: 'resource-response'

requestId: string

content?: string

blob?: string

mimeType: string

error?: string

ActivityMessage

Interface — packages/bridge/src/types.ts

Properties:

type: 'activity'

timestamp: number

ToolCallMessage

Interface — packages/bridge/src/types.ts

Properties:

type: 'tool-call'

requestId: string

toolName: string

toolInput?: Record<string, unknown>

queryId?: string

ToolRegistrationErrorMessage

Interface — packages/bridge/src/types.ts

Properties:

type: 'tool-registration-error'

toolName: string

error: string

message: string

ToolResponseMessage

Interface — packages/bridge/src/types.ts

Properties:

type: 'tool-response'

requestId: string

result: unknown

TrackedToolCall

Interface — packages/bridge/src/types.ts

Properties:

tool: string

arguments: unknown

result: unknown

QueryTracking

Interface — packages/bridge/src/types.ts

Properties:

sessionId: string

responseTool?: string

toolCalls: TrackedToolCall[]

ws: WS.WebSocket

state: QueryState

tools?: ToolMetadata[]

restrictTools?: boolean

McpRequest

Interface — packages/bridge/src/types.ts

Properties:

jsonrpc: string

id: string | number

method: string

params?: {
    name?: string;
    arguments?: Record<string, unknown>;
    _meta?: McpRequestMetaParams;
  }

McpResponse

Interface — packages/bridge/src/types.ts

Properties:

jsonrpc: string

id: string | number

result?: unknown

error?: {
    code: number;
    message: string;
    data?: unknown;
  }

ToolDefinition

Interface — packages/bridge/src/types.ts

Properties:

name: string

description: string

inputSchema?: z.core.JSONSchema.JSONSchema

outputSchema?: z.core.JSONSchema.JSONSchema

handler?: string

SessionData

Interface — packages/bridge/src/types.ts

Properties:

ws: WS.WebSocket

authToken: string

origin: string

pageTitle?: string

sessionName?: string

userAgent?: string

connectedAt: number

lastActivity: number

tools: Map<string, ToolDefinition>

resources: Map<string, ResourceMetadata>

FrontendMessage

Type — packages/bridge/src/types.ts

| AuthenticateMessage
  | RegisterToolMessage
  | RegisterResourceMessage
  | ActivityMessage
  | ToolResponseMessage
  | ResourceResponseMessage
  | QueryMessage
  | QueryCompleteClientMessage
  | QueryProgressMessage
  | QueryCancelMessage

BridgeMessage

Type — packages/bridge/src/types.ts

| AuthenticatedMessage
  | AuthenticationFailedMessage
  | ToolCallMessage
  | ToolRegistrationErrorMessage
  | ResourceReadMessage
  | QueryAcceptedMessage
  | QueryProgressMessage
  | QueryCompleteBridgeMessage
  | QueryFailureMessage
  | QueryCancelMessage

QueryState

Type — packages/bridge/src/types.ts

'active' | 'completed' | 'failed' | 'cancelled'

MissingAuthenticationErrorMessage

Variable — packages/bridge/src/schemas.ts

unknown

MissingAuthenticationErrorMessageSchema

Variable — packages/bridge/src/schemas.ts

unknown

InvalidAuthenticationErrorMessage

Variable — packages/bridge/src/schemas.ts

unknown

InvalidAuthenticationErrorMessageSchema

Variable — packages/bridge/src/schemas.ts

unknown