{"slug": "how-to-build-webmcp-tools-for-meta-ray-ban-display", "title": "How to Build WebMCP Tools for Meta Ray-Ban Display", "summary": "Meta's WebMCP lets Web Apps on Meta Ray-Ban Display register structured tools via document.modelContext.registerTool() so Meta AI can invoke page actions from spoken requests, with each tool requiring a name, description, and execute function plus optional inputSchema and annotations. The feature is coming soon and enabled per device, requires a publicly accessible HTTPS URL with a valid TLS certificate, and tools are scoped to the Web App currently open on the 600×600-pixel, touchscreen-free display. Meta recommends feature-detecting document.modelContext before registering and keeping every tool-exposed action available through the normal interface.", "body_md": "# How to Build WebMCP Tools for Meta Ray-Ban Display\n\nLearn how to build WebMCP tools for Meta Ray-Ban Display, expose actions to Meta AI, handle schemas and results, test on desktop and glasses, and design reliable voice-driven workflows.\n\nAuthored by [Nart Madi](https://nartmadi.com)\n\nPublished on September 25, 2026\n\n## What WebMCP does on Meta Ray-Ban Display\n\nWebMCP lets a Web App running on Meta Ray-Ban Display expose actions as structured tools that Meta AI can call. The wearer can ask for an action out loud and Meta AI can invoke the matching tool inside the active page instead of navigating through the interface manually with captouch or Neural Band gestures. If you're new to the standard, see our guide to [how WebMCP works](https://senro.ai/blog/how-webmcp-works).\n\nThe tool runs in the Web App itself, so it can work with the page’s DOM, application state, authenticated session, and existing APIs. For example, a shopping app could expose an `add_to_cart` tool so the wearer can ask Meta AI to add a product without stepping through several controls.\n\nThis is useful on Meta Ray-Ban Display because the screen is 600×600 pixels and has no touchscreen. WebMCP adds a natural-language path to actions that might require several focus moves or gestures. It does not replace the normal interface. Every action exposed as a tool should still be available through the app’s UI.\n\n## How WebMCP works with Meta AI\n\nWebMCP tools are scoped to the Web App currently open on Meta Ray-Ban Display. When the app loads, the page registers its tools through `document.modelContext`. Meta AI can then consider those tools whenever the wearer makes a spoken request.\n\nThe interaction follows a simple flow:\n\n1. The Web App loads and registers its available tools with `document.modelContext.registerTool()`\n2. Meta AI receives those tools while the app is in front of the wearer\n3. The wearer makes a spoken request\n4. Meta AI decides whether one of the app’s tools matches the request and passes arguments to the tool\n5. The tool’s `execute` callback runs inside the page with access to its state, DOM, and APIs\n6. The tool returns a result to Meta AI, which uses it to respond to the wearer\n\nWhen the wearer leaves the Web App, its tools are no longer available to Meta AI. If no Web App is open, the same request is handled through Meta AI’s default capabilities instead.\n\n## Before you start\n\nWebMCP for Meta Ray-Ban Display Web Apps is coming soon. During the current rollout, availability is enabled per device. Your tools will only reach Meta AI when WebMCP is available on the glasses, either through Developer Mode or the active rollout.\n\nEligibility is determined when the Web App launches and remains unchanged for that session. If you enable Developer Mode, Meta notes that you may need to restart both the glasses and the Meta AI app before WebMCP becomes available.\n\nYour Web App must be served from a publicly accessible HTTPS URL with a valid TLS certificate. HTTP-only URLs are not supported.\n\nAlways feature-detect `document.modelContext` before registering tools:\n\nIf `document.modelContext` is unavailable, calling `document.modelContext.registerTool()` would fail because the WebMCP API is not present in that session.\n\nEvery action exposed as a tool should also remain available through the normal interface. Meta recommends treating WebMCP as an accelerator rather than the only way to use the app.\n\n## How to register a WebMCP tool for Meta AI\n\nRegister tools with `document.modelContext.registerTool()`. Each tool needs a `name`, a `description`, and an `execute` function. You can also provide an `inputSchema` to describe the arguments Meta AI should pass and `annotations` to describe how the tool behaves.\n\nFor example, a travel Web App could expose a tool that saves a place for later:\n\nMeta also supports `untrustedContentHint`. Set it to `true` when a tool can return text your app did not author, such as user-generated content or third-party API responses. The hint is not a security boundary, so untrusted content should still be minimized and sanitized before it reaches Meta AI.\n\nWhen the wearer asks Meta AI to save a place, Meta AI can select `save_place`, pass the appropriate `placeId`, and invoke the tool. The `execute` callback runs inside the Web App and can use the same APIs and application state as the rest of the page.\n\nThe tool name should describe the user's intent rather than an internal function. Its description should make the purpose clear enough for Meta AI to distinguish it from other available tools. Any parameter that must be supplied should also appear in the schema's `required` array.\n\n## How Meta handles WebMCP schemas\n\nMeta supports `inputSchema` as a JSON Schema object, but its current implementation does not pass the full schema through to Meta AI. Only top-level properties such as `type` and `description` are forwarded.\n\nMore advanced constraints are not forwarded to the assistant, including:\n\n- `enum`\n- numeric ranges\n- patterns\n- `$ref`\n- nested schemas\n\nArrays and objects are also transported as strings rather than native structured values.\n\nThat means you should not rely on the schema alone to enforce valid input. Meta AI may still pass arguments that do not satisfy the schema, so every tool should validate `input` inside `execute()` before using it.\n\nThe `required` array is especially important. A parameter is only required if its name appears there. If `required` is missing or empty, Meta AI may call the tool without that parameter.\n\nFor example:\n\nHere, `placeId` is mandatory because it is explicitly listed in `required`. Even then, the tool should still check the value inside `execute()` before taking action.\n\n## How to design tool names and descriptions for Meta AI\n\nTool names should describe the wearer’s intent rather than your internal implementation. Meta recommends short, distinct names that make it easy for the assistant to choose the right action.\n\nAlthough WebMCP accepts tool names up to 128 characters, Meta prefixes each tool internally and has a 64-character budget. That leaves 57 characters for your own name before shortening can occur. Two long names that are identical in their first 57 characters can therefore collide.\n\nPrefer names such as:\n\n- `cart_add`\n- `cart_remove`\n- `save_place`\n\nAvoid long shared prefixes where the distinguishing word appears only at the end.\n\nSome names are reserved for Meta’s browser tools and cannot be used, including `openUrl`, `goBack`, `goForward`, `reload`, `getCurrentUrl`, `getPageTitle`, and `getPageText`.\n\nReserved-name failures can be silent. `registerTool()` may already have resolved before the native layer rejects the tool, so the page can appear to register it successfully even though Meta AI never receives it. Name collisions after Meta shortens long tool names can fail at the same layer.\n\nDescriptions should explain what the tool does in language Meta AI can use to choose between available tools. Put the most important information first. Meta limits tool descriptions to 1024 characters and parameter descriptions to 256 characters, with anything beyond those limits dropped.\n\nAvoid putting real answers or values the model should not guess inside parameter descriptions. Meta warns that the model may reuse an example value as an actual argument.\n\n## How WebMCP tool results work on Meta Ray-Ban Display\n\nWhen `execute()` finishes, its return value is sent back to Meta AI. What Meta AI receives depends on the shape you return.\n\nIf you return a plain JavaScript object or string, Meta serializes the value with `JSON.stringify()` and passes that JSON to Meta AI. Use this when the result contains structured information that should guide the next step.\n\nMeta AI receives the full serialized result, including fields such as `saved`, `savedPlaces`, and `next_action`. This makes structured results useful when the assistant needs to know what changed and what it should do next.\n\nYou can also return an MCP-style `content` array:\n\nIn this form, Meta AI only reads entries where `type` is `text`. Their text values are combined and passed to the assistant. Other content types and additional structured fields are ignored.\n\nThis distinction also affects errors. A fulfilled tool call is treated as successful, even if the returned object contains `isError: true` or an `error` field. To report a protocol-level failure, `execute()` must throw or reject.\n\nNot every unsuccessful outcome needs to be a failed tool call. If the tool executed correctly but encountered a normal condition the assistant can handle, return that condition as structured data instead.\n\nFor tools that change application state, return the updated state with the result whenever possible. Meta AI then knows what happened without needing another tool call to check the outcome.\n\n## Why `next_action` matters for Meta AI\n\nAfter Meta AI chooses a tool, the tool result becomes the main context it uses to decide what to do next. A `next_action` field gives the assistant an explicit instruction instead of forcing it to infer the next step from the rest of the response.\n\nFor example:\n\nWithout `next_action`, Meta AI has to interpret fields such as `saved: true` and decide how to respond. With it, the tool can make the intended follow-up clear.\n\nThis is useful when the result requires another action:\n\nMeta recommends putting this kind of guidance in the tool result because the tool description is primarily used when Meta AI is deciding which tool to call. Once the tool has run, the latest result helps steer the following response.\n\nThis also matters because speech ends the turn. Once Meta AI speaks, that turn is finished, so a result should not instruct it to say something and then call another tool. Use `next_action` to make the next step clear before the assistant decides whether to act again or respond to the wearer.\n\n`next_action` is not a special WebMCP field. It is simply structured data that your tool returns for Meta AI to interpret.\n\n## How to unregister WebMCP tools\n\nWebMCP tools should only remain registered while they are relevant to the current page or screen. When the user navigates away or a component is removed, unregister its tools so Meta AI does not continue seeing actions that no longer apply.\n\nYou can register a tool with an `AbortSignal` and abort that signal when the tool should be removed:\n\nFor example, if `save_place` only applies to a place details screen, it should be unregistered when the user leaves that screen.\n\nThis matters because stale tools can be worse than unavailable tools. If Meta AI can still see an action that no longer matches the current app state, it may choose a tool that cannot complete the wearer’s request correctly.\n\nRegister tools when they become relevant and unregister them when that context disappears.\n\n## How to test WebMCP tools without Meta Ray-Ban Display\n\nYou do not need the glasses to start testing your WebMCP implementation. Meta says the same WebMCP API can be tested in desktop Chrome with WebMCP enabled.\n\nMeta also provides a [Meta Ray-Ban Display Simulator Chrome extension](https://chromewebstore.google.com/detail/meta-ray-ban-display-simu/jpjlmmodokemlepklkdbimceggpbjcll). It gives you a 600×600 viewport, shows the tools registered by the page, logs tool responses, and includes a voice-agent interface for testing interactions closer to the glasses experience.\n\nWhen testing tool execution, use the WebMCP host-style `executeTool()` path rather than calling your tool’s `execute` function directly. This exercises the same boundary the host uses to invoke registered tools.\n\nFor example:\n\nTesting this way helps verify that the tool is correctly registered, discoverable, and callable through the WebMCP interface instead of only confirming that your underlying JavaScript function works.\n\nYou should also test failure cases, invalid arguments, cancellation, and whether tools disappear when they are no longer relevant to the current page.\n\n## How to test WebMCP tools on Meta Ray-Ban Display\n\nOnce WebMCP is enabled on the glasses, you can test your Web App directly on Meta Ray-Ban Display.\n\nOpen your Web App from **App Settings → App Connections**, then launch it from the app grid on the glasses. While the app is open, say “Hey Meta” followed by a request that should match one of your registered tools.\n\nFor example, if the page exposes `save_place`, you could ask Meta AI to save the place currently being viewed. Verify that Meta AI selects the expected tool, passes the right arguments, and responds appropriately to the result.\n\nYou should also navigate away from the Web App and repeat the request. The app’s tools should no longer be available once the page is no longer in the foreground.\n\nWhen testing on-device, check more than whether the tool runs. Verify that:\n\n- the app remains usable with captouch and Meta Neural Band gestures\n- spoken responses stay short and clear\n- invalid requests produce a useful explanation\n- unrelated requests still fall back to Meta AI’s general capabilities\n- tools disappear when the user leaves the app\n\nKeep in mind that seeing a tool through local WebMCP registry APIs does not necessarily prove that Meta AI can use it. Meta notes that a tool can still be rejected later by the native or provider layer without that rejection being visible to the page.\n\n## Meta-specific WebMCP limitations\n\nWebMCP on Meta Ray-Ban Display has several limitations that affect how tools should be designed.\n\nTools are only available while the Web App is open in the foreground. When the wearer leaves the app, its tools disappear from Meta AI. This also means Meta AI cannot currently compose tools across multiple Web Apps.\n\nAssistant-initiated tool calls have a fixed 10-second deadline. If a tool takes longer, Meta reports a timeout, aborts the call on a best-effort basis, and ignores any result that arrives afterward. Long-running work should therefore be started asynchronously when possible, with the tool returning promptly.\n\nVoice interaction also adds latency. A tool call will generally take longer than answering a request without invoking a tool, so tools should be reserved for actions that actually need access to the Web App.\n\nAuthentication can also be harder on glasses than on a desktop or phone. Where possible, the wearer should already be signed in before opening the Web App on Meta Ray-Ban Display.\n\nFinally, registering a tool locally does not guarantee that Meta AI will receive it. Meta notes that a tool can still be rejected later by the native or provider layer, and that rejection may not be visible to the page.\n\n## WebMCP best practices for Meta AI glasses\n\nKeep the tool surface small. Meta recommends exposing one or two tools that complete meaningful tasks end to end rather than creating a separate tool for every internal function.\n\nDesign each tool around a clear user intent. Names should be short and distinct, descriptions should explain when the tool should be used, and required parameters should be obvious from the schema.\n\nReturn results that tell Meta AI what happened and what should happen next. Include the updated state after mutations and use fields such as `next_action` when the assistant needs explicit follow-up guidance.\n\nValidate every argument inside `execute()`. Meta AI chooses the tool inputs, so schema definitions alone should not be treated as validation. Do not perform destructive or irreversible actions simply because the supplied arguments look plausible.\n\nKeep spoken responses short. Meta recommends saying less than the screen shows, since the wearer can already see the Web App. A concise sentence is usually better than reading the full result aloud.\n\nTreat the Web App as the source of truth. The page should verify whether an action actually succeeded instead of relying on Meta AI's description of the outcome.\n\nRegister tools only while they are relevant and remove them when the user leaves that context. A stale tool can cause Meta AI to select an action that no longer matches the current state of the app.\n\nFinally, keep the normal interface available. WebMCP should provide a faster voice-driven path through the app, not replace the app's existing controls.\n\n## WebMCP vs. Meta AI Connectors\n\nWebMCP and Meta AI Connectors both let Meta AI call developer-defined tools, but they connect to Meta AI in different ways.\n\nWith WebMCP, the tools belong to a Web App running on Meta Ray-Ban Display. The page registers them through `document.modelContext`, and Meta AI can use them while that Web App is open. The tool executes inside the page, where it can access the app’s DOM, state, authenticated session, and existing APIs. [Learn more in Meta’s official WebMCP documentation](https://wearables.developer.meta.com/docs/develop/webapps/agent-tools?utm_source=senro&utm_medium=referral&utm_campaign=meta-ray-ban-webmcp-guide&utm_content=webmcp-docs).\n\nMeta AI Connectors connect a service directly to Meta AI instead. You expose an existing API through Meta’s connector tooling or an MCP server, and Meta AI can call those actions without the user opening or remaining inside a Web App. Meta says one connector can work across AI glasses, the Meta AI app, and the web. [Learn more about Meta AI Connectors in Meta’s official documentation](https://dev.meta.ai/products/connectors?utm_source=senro&utm_medium=referral&utm_campaign=meta-ray-ban-webmcp-guide&utm_content=meta-ai-connectors).\n\nThe difference is where the tools live and when they are available:\n\n|  | WebMCP | Meta AI Connectors | \n|---|---|---|\n| Connects | A Web App | A service or API | \n| Integration | `document.modelContext` | API or MCP | \n| Runs | Inside the active Web App | Through the connected service | \n| Availability | While the Web App is open | Through Meta AI across supported surfaces | \n| Requires a Web App | Yes | No | \n\nIf you want Meta AI to control actions inside a Web App on Meta Ray-Ban Display, WebMCP is the relevant path. If you want a service to be accessible directly through Meta AI across multiple surfaces, Meta AI Connectors are designed for that use case. For a broader look at how the two protocols differ, see [WebMCP vs. MCP](https://senro.ai/blog/webmcp-vs-mcp).\n\n## WebMCP reliability on Meta Ray-Ban Display\n\nA WebMCP tool being registered does not mean the full interaction will work reliably. Meta AI still has to choose the right tool, pass appropriate arguments, receive the result within the 10-second deadline, and use that result correctly in its response to the wearer.\n\nTool inputs should also be treated as untrusted. Meta AI decides what arguments to send, so the Web App should validate every input before acting on it. For tools that change application state, the result should clearly report what changed and, when needed, what should happen next.\n\nTool availability is another source of failure. Tools should only remain registered while they are relevant to the current screen or state. A stale tool can cause Meta AI to select an action that no longer applies.\n\nThere are also failures the page cannot directly observe. Meta notes that a tool can appear in the local WebMCP registry but still be rejected later by the native or provider layer. Checking `getTools()` alone therefore does not prove that the complete Meta AI interaction works.\n\nReliable WebMCP implementations need to be tested across the full flow: tool discovery, tool selection, arguments, execution, returned state, timeouts, failures, and the final response Meta AI gives the wearer.\n\n[Senro](https://senro.ai/) is built for this layer of WebMCP reliability. It helps developers evaluate WebMCP implementations across LLMs and languages, test whether agents select and use tools correctly, and monitor tool calls in production.\n\nInstead of only checking whether a tool works in isolation, Senro helps test whether an AI agent can reliably use it to complete the intended task.\n\n## Frequently asked questions\n\n### Does Meta Ray-Ban Display support WebMCP?\n\nYes. Meta has implemented WebMCP for Web Apps on Meta Ray-Ban Display through `document.modelContext`. Meta says the feature is coming soon. During the current rollout, availability is enabled per device.\n\n### Does Meta AI call WebMCP tools directly?\n\nMeta AI can select and invoke tools registered by the Web App currently open on Meta Ray-Ban Display. The tool's `execute()` function then runs inside the page.\n\n### Do I need Meta Ray-Ban Display to develop WebMCP tools?\n\nNo. You can develop and test WebMCP tools in desktop Chrome with WebMCP enabled. Meta also provides a Meta Ray-Ban Display Simulator Chrome extension for testing the 600×600 interface and tool interactions.\n\n### How long can a WebMCP tool run on Meta Ray-Ban Display?\n\nAssistant-initiated tool calls have a fixed 10-second deadline. If the tool exceeds that limit, Meta reports a timeout and ignores any result returned afterward.\n\n### Does Meta support the full WebMCP `inputSchema`?\n\nNo. Meta currently forwards only part of the schema to Meta AI. Constraints such as `enum`, ranges, patterns, `$ref`, and nested schemas are not forwarded, so tools should validate inputs themselves.\n\n### Can WebMCP tools run when the Web App is closed?\n\nNo. Tools are scoped to the Web App currently in the foreground. When the wearer leaves the app, those tools are no longer available to Meta AI.\n\n### What is the difference between WebMCP and Meta AI Connectors?\n\nWebMCP exposes tools from an active Web App to Meta AI. Meta AI Connectors expose a service or API directly to Meta AI and are not tied to a Web App being open.", "url": "https://wpnews.pro/news/how-to-build-webmcp-tools-for-meta-ray-ban-display", "canonical_source": "https://senro.ai/blog/how-to-build-webmcp-tools-for-meta-ray-ban-display", "published_at": "2026-09-25 12:40:18+00:00", "updated_at": "2026-10-09 16:52:17.569983+00:00", "lang": "en", "topics": ["ai-agents", "agent-protocols", "ai-products", "developer-tools", "ai-tools"], "entities": ["Meta", "Meta Ray-Ban Display", "WebMCP", "Meta AI", "document.modelContext", "Nart Madi", "Neural Band"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/how-to-build-webmcp-tools-for-meta-ray-ban-display", "markdown": "https://wpnews.pro/news/how-to-build-webmcp-tools-for-meta-ray-ban-display.md", "text": "https://wpnews.pro/news/how-to-build-webmcp-tools-for-meta-ray-ban-display.txt", "jsonld": "https://wpnews.pro/news/how-to-build-webmcp-tools-for-meta-ray-ban-display.jsonld"}}