APIs

The server exposes transport-facing APIs for MDP clients. This section is split into connection setup, message events, and external interfaces.

Read by task

Goal	Start here
Open a bidirectional session	WebSocket
Use request-response transport instead of sockets	HTTP Loop
Bootstrap browser auth before opening a websocket	Auth Bootstrap
Probe whether a port is serving MDP	GET /mdp/meta
Update a connected client's path catalog	updateClientCatalog
Look up websocket message event types	registerClient, callClient, ping
Check exact HTTP request and response contracts	POST /mdp/http-loop/connect, POST /mdp/auth, GET /mdp/meta

Connection Setup

Surface	Entry point	Notes
WebSocket	ws://127.0.0.1:47372	Bidirectional JSON MDP messages
HTTP Loop	/mdp/http-loop/connect	Session-based long-poll transport
Auth Bootstrap	/mdp/auth	Cookie bootstrap mainly for browser websocket clients
Metadata Probe	/mdp/meta	Identify an MDP server and read discovery hints

Message Events

Event	Direction	Purpose
registerClient	Client -> Server	Register one client descriptor and paths
updateClientCatalog	Client -> Server	Replace one registered path catalog
unregisterClient	Client -> Server	Remove one registered client session
callClient	Server -> Client	Invoke one method+path target on a client
callClientResult	Client -> Server	Return a routed invocation result
ping	Both directions	Heartbeat keepalive
pong	Both directions	Heartbeat acknowledgement

External Interfaces

Interface	Method	Purpose
POST /mdp/http-loop/connect	POST	Create one HTTP loop session
POST /mdp/http-loop/send	POST	Send one client-to-server message
GET /mdp/http-loop/poll	GET	Receive one server-to-client message
POST /mdp/http-loop/disconnect	POST	Close one HTTP loop session
POST /mdp/auth	POST	Issue one auth cookie
DELETE /mdp/auth	DELETE	Clear one auth cookie
GET /mdp/meta	GET	Probe one server for MDP metadata
GET /skills/:clientId/*skillPath	GET	Read one skill over the direct HTTP route
GET /:clientId/skills/*skillPath	GET	Read one skill over the nested HTTP route

Shared JSON types

AuthContext:

{
  "scheme": "Bearer",
  "token": "client-session-token",
  "headers": {
    "x-mdp-auth-tenant": "demo"
  },
  "metadata": {
    "role": "operator"
  }
}

SerializedError:

{
  "code": "handler_error",
  "message": "Something failed",
  "details": {
    "reason": "optional"
  }
}

MDP client catalogs are path-based. Each descriptor in client.paths is one of:

• an endpoint with an HTTP-like method plus path
• a prompt served at a *.prompt.md path and invoked with GET
• a skill served at a *.skill.md path and invoked with GET

Relationship to bridge tools

These APIs are for MDP clients. MCP hosts do not call them directly. MCP hosts use the bridge Tools.