Repository navigation
Allow iframes to declare tools #57
Description
The proposal currently restricts only the top-level browsing context to declare tools, see here: "Only a top-level browsing context, such as a browser tab can be a model context provider."
This means embedded frames can't declare tools, same or cross-origin. This was discussed at the last TPAC, notes here.
Activity
domfarolino commentedon Jan 28, 2026
Discussed with some folks today, and I agree with the direction the meeting seemed to take towards the end, which is creating a permission policy so the top-level can delegate tool registration to a cross-origin iframe and so on (note here):
Note that this would be particularly important to support the MCP Apps "registerTool()" use case that @ochafik is working on in modelcontextprotocol/ext-apps#72.
The good news is I do think this could be polyfilled in the meantime.
domfarolino commentedon Jan 28, 2026
In particular, we should really try to see if we could build MCP Apps's proposed tool registration & execution mechanism on top of native WebMCP, polyfilling gaps where needed.
johannhof commentedon Jan 28, 2026
I agree that a permissions policy would be a great idea here to protect the embedder from 3P tools while making them usable - we should be a bit mindful of attacks coming from the embedder as well though.
Giving embedders the ability to direct the agent to use tools from other origins without those origins also agreeing to their usage might go against the same-origin-policy, though this is uncharted territory of course.
victorhuangwq commentedon Jan 30, 2026
Discussing briefly with @lflores-ms, this could be a good fit for document policy, https://github.com/WICG/document-policy/blob/main/document-policy-explainer.md given that there is a need for two-way opt-in, by both the embedder and embeddee.
johannhof commentedon Feb 4, 2026
Thanks Victor! I agree that this might be a good fit. Would be great to get these security requirements defined in the spec.
Starborn commentedon Feb 20, 2026
On the permission policy approach and the WebMCP/MCP architectural boundary
The permission policy direction makes sense and the two-way opt-in framing (embedder + embeddee both agreeing) is the right security model. I want to add a consideration that hasn't been made explicit yet.
The MCP Apps registerTool() use case (@ochafik, modelcontextprotocol/ext-apps#72) operates at a different architectural layer than WebMCP's browser-native tool declaration. MCP Apps is a network-layer protocol; WebMCP is a browser security architecture. Building MCP Apps tool registration on top of native WebMCP (as @domfarolino suggests) is the right direction, but the translation contract between the two layers needs to be explicit in the spec, not left to implementations.
Specifically: when a cross-origin iframe registers a tool via registerTool() and that tool surfaces to the outer agent through WebMCP, who holds the permission boundary? The embedder's permission policy controls whether the iframe can declare tools, but the agent's trust model also needs to know whose origin the tool is scoped to. If that scoping is ambiguous, an embedder could inadvertently expose a cross-origin iframe's tools to an agent with broader permissions than the iframe's origin would warrant on its own -- the attack vector @johannhof flags.
Suggestion: the spec should require that tool provenance (origin of declaration) travels with tool registration through the permission policy chain, so agents can apply origin-appropriate trust at invocation time, not just at registration time.
This connects to the broader work on agent trust and identity being discussed in issue #96.
Posted on behalf of Claude See also webMCP not MCP https://github.com/Starborn/webmcp/blob/main/WebMCnotMCP.md
victorhuangwq commentedon Feb 20, 2026
From some of our internal explorations, a problem that might come up more in allowing iframes to declare tools, is tool name conflict. which now reading the november's meeting notes, is something that has already been briefly discussed.
I don't think iframes should be allowed to access/modify the parent frame's tool list (or the other way around) as possibly implied by conversations in #101, overwriting risk shouldn't exist. But I think it's reasonable for iframes to declare the tools of the same name as that of the parent frame, or at least there shouldn't be a restriction in that case.
Double keying on origin/tool-name might be a way to go? Not sure if this would be an implementors decision or part of the spec however.
Starborn commentedon Feb 21, 2026
@victorhuangwq
Thank you @victorhuangwq for raising this -- the tool name conflict across iframe boundaries is important to address clearly in the spec. agree that iframes should not be able to access or modify the parent frame's tool list, and vice versa -- this aligns with Same-Origin Policy principles and the existing security model of the web. The overwriting risk you mention is real and the isolation boundary should be explicit in the spec, not left to implementor interpretation.
On the question of whether iframes can declare tools with the same name as the parent frame: we lean toward allowing this, precisely because of the isolation boundary. If the two contexts are genuinely isolated, name collision is not a conflict -- it's just coincidence, similar to two separate MCP servers both exposing a tool called search. The agent (or browser intermediary) would need to resolve which tool to invoke based on context, not by a flat global namespace.
The double-keying approach you suggest -- origin/tool-name -- seems like the right direction, it warrants being specified rather than left to implementors. Leaving it as an implementor decision risks inconsistent behavior across browsers, which would make it very difficult for developers and agents to reason about tool identity reliably. Would it be worth opening a dedicated issue for the tool namespace/disambiguation question? It seems distinct enough from the iframe permission boundary question to warrant its own thread, and the double-keying proposal deserves focused discussion.
Alternatives to double-keying:
Namespacing by prefix -- tools declared in iframes get a prefix like iframe::search or widget::search. Simpler but arbitrary, and who assigns the prefix becomes a new problem.
Flat global namespace with strict uniqueness -- no two tools anywhere in the page tree can share a name. Simple to reason about but very restrictive; breaks legitimate use cases where independent components naturally use the same tool names.
Scoped registries -- each browsing context has its own completely isolated tool registry, and the agent has to explicitly select which context's tools to invoke. Clean isolation but adds complexity to the agent interaction model.
Tool shadowing with explicit override flags -- iframes can declare same-named tools, with explicit precedence rules (parent wins, or most-local wins). Familiar from CSS cascade thinking but introduces fragility.
The general good practice philosophy leans toward prescribing one interoperable solution once the design space is understood, but documenting the alternatives considered and why they were rejected. That's what the "alternatives considered" sections in explainers are for. Offering multiple options in the spec itself usually signals the group hasn't reached consensus yet, which is fine at this stage but creates implementor confusion later.
bvandersloot-mozilla commentedon Mar 2, 2026
The discussion here seems to match the powerful-feature use case of Feature Policy. The embedee's use of the API is their opt in, no?
Seems reasonable if you want mandated separate namespaces. A
listToolsendpoint makes this more complicated. I'd expect all tools in the window tree to be returned. Should we return the serialized origin inside of the tool description returned fromlistTools?victorhuangwq commentedon Mar 3, 2026
permission policy (which feature policy evolved into (?) unless i'm missing something about feature policy ) sounds like the better fit by name, because in some sense webmcp is indeed a "capability". but i think document policy allows for a more "secure by default" posture. from what i understand, here's what it would look like in the permission policy and document policy "world"
permission policy:
document policy:
If we go the permission policy route, we need developers to be very aware of the fact that if their webmcp will be available on any page they are embedded in.... we could say they should just use CSP to prevent embedding, but that feels like a "after the fact" fix for a problem we’re just now creating. since we’re introducing something new, maybe we can avoid forcing people to track their own embeddings just to stay secure.
I see... in my current thoughts, even with the ongoing discussions to have listTools as part of the WebMCP api, the JS context calling listTools should only list tools from it's own context, and not get information from it's child frame.
bvandersloot-mozilla commentedon Mar 3, 2026
Yes, s/feature/permissions/.
Oh, this response is interesting!
If this is the case, I'd be fine with this not even using either of these techniques (assuming invokeTool follows the same pattern). But that means there is one context provider per frame rather than per page, which is the unexpected part to me.
@yoavweiss seems to have made the same assumption as I did in posing #117.
And wrt document policy vs permissions policy, I don't see why the behavior for the embedee in either case is different. It's just a difference in using a HTTP response header or just not using the API in the response body. Although to be fair I am just going off of a read of the explainer. My initial reaction is based on wanting to to not depend on a mechanism that is Chrome-only when another option is broadly supported.
johannhof commentedon Mar 3, 2026
listTools would list all exposed tools, right? That could include 3P iframes if they set the right headers.
I agree with @victorhuangwq that document policy seems vastly superior here, both in terms of ergonomics and security, as it's a much more explicit choice to add the header vs "just not using the API in the response body". We would really want to force embedded iframes to explicitly allow their individual tools to be used in that specific context, vs. trusting them to not have the same code run everywhere.
victorhuangwq commentedon Mar 5, 2026
When developers do cross-origin communication today (e.g.
postMessage), both origins expect to write origin checks. WebMCP tools don't carry that expectation. If we're trending towards listTools being able to surface tools from all frames, it has to be explicit opt-in by the child frame(s). Otherwise we're turning WebMCP into a cross-origin channel without developers expecting it to be one, basically allowing cross-origin execution that embeddees never signed up for.@bvandersloot-mozilla on the note about depending on document policy, which is only implemented in Chrome/Chromium as of now, that's a fair concern. But I think the security model should drive the choice of mechanism. If document policy is the right primitive, we should argue for broader adoption of it.
We could consider splitting this across two mechanisms: permissions policy for the parent frame side (controlling whether the child can use WebMCP at all), and something WebMCP-specific for the child frame side, like
navigator.modelContext.setAllowedOrigins, defaulting to same-origin only. But that feels like we're basically rebuilding document policy's negotiation model? not opposed to it though.8 remaining items
anssiko commentedon Mar 19, 2026
domfarolino commentedon Mar 19, 2026
Note that @markafoltz raised a good point on today's call about coming up with some serialization scheme to disambiguate name collisions across frames. The way MCP handles it (https://modelcontextprotocol.io/legacy/concepts/tools#tool-name-conflicts) pretty much leaves it up to the client, which makes sense since the tool names aren't exposed to any platform directly.
If we go the route of exposing an iframe's tools to its parent's tool enumeration API, then we'll need some way of namespacing these APIs, or something like that.
MiguelsPizza commentedon Mar 19, 2026
After the conversation today, I'd like to play devil's advocate here and throw out the idea of not having WebMCP be a special case for iframes at all, or at least backlogging it until both the WebMCP and MCP Apps APIs mature. Now that we have an API to list/call/listen to tools in the same document context, it's trivial to relay them over postMessage between host and child.
In fact, this use case is already well supported by an existing RPC protocol: MCP!, which concerns itself with this exact problem (how do we discover, listen for and call tools between separate contexts).
MCP-Apps and the webmcp polyfill currently use postmessage. We'd just be reusing the security infrastructure that's already there. As potential web features go, this one is uniquely well supported and used in userland. It might be better to sit back and wait for what people run into. I had a user run into the exact iframe host name collision @markafoltz described and ended up adding a prefix to the webmcp iframe polyfill
victorhuangwq commentedon Mar 20, 2026
@MiguelsPizza appreciate you playing devil's advocate here. For use case 2 (To allow cross frame calling of tools) from my breakdown above, relaying it over postMessage as a current solution can make sense (though ergonomics is worth considering here). I think waiting can be reasonable, unless someone else already has a strong use case / can see demand for it.
For use case 1 though, I think it is slightly different. Say I embed a Calendly widget on my site so visitors can book a meeting. Calendly is designed to be iframed anywhere, you just copy and paste
<iframe src="https://calendly.com/your-link">in the html. In the hypothetical scenario where Calendly adds WebMCP tools (e.g. "book a 30-minute meeting"), as a site owner, I would want to opt into the UA to be able to see Calendly's tools without needing to set up a postMessage bridge. I'm not trying to call Calendly's tools from my page, I just want the UA to see them.That said, Calendly should still explicitly opt in to exposing tools when embedded. Once both sides agree, the UA sees the tools. I would say though, After looking at frame ancestors, I am more open to the idea of wildcards (for something like Calendly scenario)
johannhof commentedon Mar 20, 2026
+1 to @victorhuangwq on the motivation for this - delegating capabilities to iframes makes composition on the web both safer and easier, because the practical alternative that happens is that developers will embed JS scripts instead, which has much worse implications for security, among other things.
victorhuangwq commentedon Mar 20, 2026
cc @clelland, for context the group just resolved to explore Document Policy as a bi-directional opt-in mechanism for iframe WebMCP tool exposure here. A possible alternative being discussed is Permissions Policy for the parent side + something WebMCP-specific for the child-side opt-in. Since you've thought a lot about this space, would be curious to hear your take on the right primitive here.
markafoltz commentedon Apr 2, 2026
Per today's call, I filed #160 to provide a forum to discuss the name collision issue, separate from the access control issue.
schneidergithub commentedon Apr 9, 2026
I would like to contribute my thoughts here, security being my primary focus. There are some clever hacking tricks that relate to mobile apps, where an app can go through the review & security process to be approved, and then down the road make a malicious update. I can see something similar happening here. Imagine this scenario:
A top-level site embeds a third-party iframe.
The iframe is allowed to declare tools.
The iframe origin is reviewed and appears benign.
Weeks later, the iframe provider ships new code, changes infrastructure, adds analytics, or is compromised.
The already-authorized integration now exposes different behavior to the agent, without any new explicit trust event.
domfarolino commentedon Apr 9, 2026
Yeah, unfortunately that's basically just how the web works. With postMessage(), permissions policy, importing script into your origin, and everything else—no content on the web is "frozen" at "review time", with the exception of assets whose execution/application is blocked by subresource integrity (which doesn't work across the iframe boundary anyways—that's more about protection inside your origin). Otherwise, when you delegate a powerful feature to a 3p origin, or postMessage() it, you are fully trusting what's on the other side, and you're trusting it to evolve in a way that's compatible with your goals.
Just like there isn't a way to reliably inspect the 3p code that will respond to your postMessage(), there isn't a way to reliably inspect the 3p code that implements a given tool call. The platform's responsibility is to ensure that everyone knows who they're talking to, and who their tools are exposed to and invoked from, but that's probably it.
schneidergithub commentedon Apr 9, 2026
Fair points @domfarolino - I personally feel like iframes are a special case since it's embedded, delegated, with origin-crossing relationships. However, I admit I'm not an expert on the finer details and defer to the smarter people in this discussion! Thank you for hearing my concerns and I appreciate your insightful response!
johannhof commentedon Apr 10, 2026
While I agree with @domfarolino generally it should be said that there are some trust mechanisms like Subresource Integrity that address these types of issues. It's maybe not an immediate concern for this API, but we could consider adding hash based trust mechanisms for embedders to verify that the tools they are being given are exactly the same (which might prevent data exfiltration etc.) on the page.
It should be noted that there are still tool responses, which are harder to check, so we'd have to consider whether this actually provides a meaningful level of assurance.