Proposal: Standard MCP-to-WebMCP tool format converter #84

Activity

1. domfarolino

   added

   backlog

   on Mar 4, 2026
2. markafoltz

   added

   enhancementNew feature or requestNew feature or request

   on Sep 24, 2026
3. manticorevault commented on Oct 7, 2026

   

   manticorevault

   on Oct 7, 2026

   Last edited by manticorevault

   More actions

   Adding the point of view based on a converter that's already in use.

   I work on snyk.io. We are wiring a read-only content-search tool up as a server-side MCP tool and registering it in document.modelContext through mcp-handler's experimental_webMcp bridge. Not in production yet. The bridge is close to what is presented in Option B: the server serves a script from GET /mcp?webmcp-script that runs initialize and tools/list, keeps an allowlisted subset, calls registerTool() for each, and forwards execute to tools/call. Source: src/webmcp/script-handler.ts.

   Against the four things the proposal says developers currently do by hand:

   1. Schema mapping was a non-issue. name and inputSchema pass through unchanged. The one mismatch is description, required on ModelContextTool and optional in MCP, so the bridge falls back to title and then name.

   2. Response format is where the sketch in this issue and the bridge seem to disagree. The sketch returns result.result when content is present. The bridge returns the whole CallToolResult from execute, and WebMCP JSON-serializes whatever that resolves to, so the agent sees MCP's envelope (content, structuredContent, isError) instead of something more WebMCP-shaped. Our tool fills both content and structuredContent, so in this way the agent receives both. I don't think either choice is obviously right (which is the useful part).

   3. Errors are the one part a converter can't paper over. An isError: true result resolves normally and the text reaches the agent. A JSON-RPC or HTTP error rejects execute, and the spec completes that as a failure while only optionally logging the reason, so the agent learns the call failed and not why. The sketch avoids that by returning the error as content. That split seems worth writing down, and it depends on No structured way to signal a tool's refusal, distinct from success or a schema-validation error #282 and Define specific errors for tool execution failures #323, from what I could see.

   4. Metadata: only readOnlyHint is copied. idempotentHint and openWorldHint have nowhere to go. destructiveHint is dropped instead of mapped onto consequentialHint, so a destructive MCP tool arrives looking neither read-only nor consequential. outputSchema is dropped because ModelContextTool has no field for it yet (based on Introduce outputSchema (was: Should output also have a schema?) #9).

   On the questions at the end: I'd keep a converter as informative guidance. Streaming isn't handled, so the bridge reads one finite SSE response and ignores progress notifications. Resources, prompts and sampling are ignored, tools only. The part I'd want written down anyway is the error mapping, forcing destructiveHint to collapse to consequentialHint: false.

   One thing about Option B as sketched, registerMCPTools(tools, { endpoint, headers }): it registers every tool and sends the caller's headers. The bridge won't start without an allowlist. We allowlist one read-only tool and set credentials: "omit", because anything in the page can invoke a registered tool as the visitor. That feels like part of the advice even though it isn't part of the format.