You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
MCP Apps are rendered in a sandboxed iframe. Accessibility depends heavily on both the host and the app.
We should validate that the spec provides the hooks and constraints needed for strong accessibility (keyboard/focus management, screen reader support, labeling, theming/contrast, zoom/magnification behavior) and that apps must meet these expectations.
Reacted by Steven J Hatzakis, oleksandrh-vista, willsutton and Eli Chadwick
Reacted by Ola Hungerford, Angie Jones and willsutton
First, thanks for creating the issue. I'm working with the American Council of the Blind on some MCP integrations and in my discussions with them, they are VERY excited about both the current state as well as potential future state for AI generally. I've got a meeting with them tomorrow morning and I'm going to be asking about getting a pool of folks together who might be able to help with real-world a11y testing, and the people on their end I've worked with in the past on similar tasks have been quite thorough.
Anyway - quick first pass on this issue: I think we should separate what the spec can standardize from what each host must implement, and I'd like some input on the below breakdown:
Where I think we’re at now:
The spec already gives us good plumbing for host < -- > app coordination (sandboxing, host context, theming tokens, display mode, sizing, safe-area insets, context change notifications).
That plumbing helps accessibility, but it doesn’t yet define clear accessibility expectations.
In particular, keyboard/focus behavior across host + iframe boundaries, screen reader semantics/labeling expectations, and zoom/reflow behavior are not explicitly spelled out as requirements.
Things I think we need to clarify next:
Which accessibility behaviors should be required by the spec (host-agnostic contract)?
Which behaviors are host-owned implementation details (Claude/ChatGPT/etc. UI patterns)?
Which behaviors are app-owned (semantic HTML, focus-visible, labels, announcements, etc.)?
What should be tested for conformance vs recommended as best practice?
Create a host/app/spec responsibility matrix for key accessibility areas (keyboard/focus, SR support, labeling, contrast/theming, zoom/magnification).
Turn that matrix into a practical test checklist we can run across basic-host + at least one production host.
Use those findings to decide:
doc-only guidance,
normative spec clarifications,
or protocol additions (if any gaps can’t be solved with current hooks).
Bring in external SR/AT validation (ACB resources (see above) and others) once the checklist is stable, so we test against real workflows, not just assumptions.
What do you think? I can also put together the initial responsibility matrix/checklist in a follow-up.
Hi @idosal — happy to see this issue. I’m head of innovation at AbilityNet (UK accessibility charity).
The host/app split in MCP Apps is a genuinely interesting accessibility surface — the rendering layer being separable from the source service creates opportunities (host can enforce semantic structure, focus patterns, AT conventions consistently) but also risks (status messages crossing the iframe boundary, focus management at sandbox edges, host conformance silence in the current spec).
I’m planning to spend some time auditing the current draft and the example apps against WCAG 2.2 AA over the coming month, and will follow up here with concrete findings.
A couple of questions in the meantime that would help shape that:
Is the intent for accessibility to live as part of the core MCP Apps spec, or as a profile/extension on top?
Are there host implementations you’d specifically like the audit to cover beyond basic-host?
Has the WG discussed accessibility informally on Discord that I should catch up on before commenting further?
Hi @willsutton, I was just on a call with Jeff Bishop at ACB when I saw your comment come in, he mentioned he knows you. Your perspective on the host/app accessibility surface (and the planned WCAG 2.2 AA audit of the draft + example apps) is going to be incredibly valuable. Thank you.
Quick answers to your questions, from my perspective/opinion:
Core spec vs. profile/extension: My own take (and what I proposed a bit earlier in the thread) is that the host/app contract around accessibility should live in the core MCP Apps spec wherever we can make it host-agnostic and enforceable (focus management across iframe boundaries, status-message announcements, theming/contrast guarantees, safe-area/zoom behavior, etc.). Anything that ends up being host-specific UI patterns or deeper guidance could be non-normative appendices or a separate profile. Definitely something the WG should discuss explicitly.
Hosts to cover: basic-host is the highest-priority reference implementation. Any production hosts you’re able to test (Claude Desktop, ChatGPT, etc.) would be excellent additional data points.
Discord: There’s an active thread in the #mcp-apps-wg server called “a11y for Apps” (started ~April 4 2026). If you drop me your Discord handle I’ll add you immediately, or you can scroll back and jump in.
On the ACB side: As I said earlier, I just got off the phone with my contacts at the American Council of the Blind. Our call was mostly about broader AI adoption, but in an earlier conversation Dan (ACB president) said something that’s stuck with me and I think gives this issue real urgency: “If you get it right out of the gate we’re not a generation behind again.” They’re very excited and have already offered to pull together a pool of technical users for real-world testing once we have something stable to run against.
I’ll post an initial draft of the host/app/spec responsibility matrix and practical test checklist I mentioned earlier as a strawman/starting point for discussion. I’d love to incorporate your audit findings and coordinate with both AbilityNet and ACB folks so we’re testing against real workflows (screen readers, keyboard-only, magnification, etc.).
Let me know how you’d like to sync up and of course quite happy to facilitate any intros (sounds like you may not need them XD )
@phillamb168 Thanks for the warm welcome. Discord handle is suttzz it would be great to be added to the a11y for Apps thread. I’ll read back through it before commenting.
I agree on the core-spec / non-normative-appendix split. Host-agnostic and enforceable in core, host-specific patterns as appendices or a profile, feels right.
Quick thought on the matrix as additions for WG discussion:
Cognitive accessibility as its own row. Probably the strongest opportunity the host/app split creates — the host can offer plain-language alternatives, simplification, and mode-shifting on demand, none of which retrofit that well onto traditional sites.
On the audit: spec and basic-host feel like good starting points. I’ll post findings in the Discord thread first so the WG can shape what comes back here.
AbilityNet also has an existing diverse user research capability — happy to explore coordinating with ACB when the time is right, the two together would be a strong evidence base.
Sorry for the super mega delayed response... based on the feedback, I'd propose the following guiding principle:
Each layer owns accessibility for what it renders and directly controls. Behavior that crosses the host/app boundary is shared responsibility and, where interoperability is required, belongs in the spec.
Based on @willsutton 's suggestion I'd also distinguish between:
Ensure all in-app controls are keyboard operable, with logical tab order and no internal keyboard traps.
Ensure the app itself is reachable in the host's focus order and users can move predictably between host and app.
Define any required cross-boundary focus behavior or coordination mechanisms.
Focus lifecycle / iframe boundary
Manage focus appropriately within the app and expose meaningful focus targets.
Own focus entry into the app, return/restoration when the app closes or changes state, and interaction with surrounding host UI.
Define testable expectations for focus handoff/restoration where host/app coordination is required.
Screen reader semantics
Provide correct semantic HTML, roles, names, states, relationships, and announcements for app content.
Ensure the embedded app has an accessible identity/context within the surrounding host and that host-controlled lifecycle states are exposed accessibly.
Ensure sufficient metadata/hooks exist for hosts to identify and describe embedded app views.
Labels, instructions, and errors
Label in-app controls and expose instructions, validation, and errors accessibly.
Label host-provided controls and chrome surrounding the app.
Define any interoperable metadata required to give an app/view an accessible name or description.
Contrast, theming, and user preferences
Render accessible content under supported themes and avoid relying on color alone.
Supply accessible defaults and propagate relevant host/user preferences where supported.
Define interoperable preference/theme signals and their semantics; host-specific UI belongs in guidance.
Zoom, magnification, and reflow
Support responsive reflow and content scaling without clipping or loss of functionality.
Avoid constraining the embedded view in ways that prevent browser zoom, magnification, or effective resizing.
Ensure sizing/resize mechanisms allow accessible reflow and do not require assumptions that break magnification.
Cognitive accessibility
Keep app interactions understandable and predictable; provide clear language, context, error recovery, and appropriate confirmation/undo patterns.
Where appropriate, hosts may provide consistent interaction patterns or alternative/simplified presentations across apps.
Core should only standardize hooks or metadata needed for interoperable behavior; host-specific simplification/plain-language patterns should live in non-normative guidance or profiles.
Status, loading, and transitions
Expose status changes originating inside the app.
Expose host-controlled loading, mounting, errors, dismissal, and other lifecycle changes.
Define coordination where a state originates on one side of the boundary but needs to be communicated accessibly on the other.
Conformance/testing
Test the accessibility of the rendered app itself.
Test the accessible embedding and surrounding host experience.
Provide testable requirements for boundary behaviors rather than attempting to assign whole-experience WCAG conformance to one side.
With that in mind, and trying to move towards something actionable, I'd propose the following next steps:
Audit the basic host plus a representative set of example apps against WCAG 2.2 AA, but record findings as a gap ledger rather than a prose report. Each finding gets classified as App, Host, or Boundary/Spec.
Move app-only and host-only findings out of this issue into example/docs/guidance work as appropriate.
Turn the first clear Boundary/Spec findings into a small draft spec PR, rather than waiting for the entire audit to be complete.
My initial candidate slice would be accessible view naming & focus lifecycle across the host/iframe boundary, since those seem both protocol-relevant and narrow enough to define and test concretely.
Add or extend a minimal test fixture around that behavior so that the proposed normative language has an observable conformance case.
Unless there's disagreement with the responsibility split above, I'd suggest treating this as the working model and start moving from the matrix into that first narrow spec/test slice rather than trying to resolve every accessibility question in this thread first... thoughts?
I'd like to pick up the "Contrast, theming, and user preferences" row from @phillamb168's matrix, where the spec's job is to "define interoperable preference/theme signals and their semantics."
What I tested
A harness matching the real host structure (host → sandbox proxy → app, three different sites, app sandboxed with allow-scripts) in Chrome, Edge, Firefox, WebKit, a native macOS WKWebView host and Electron, using real macOS settings (Increase Contrast, Reduce Motion). Note for anyone repeating this: Playwright's emulateMedia sets the value in each Chromium frame separately, so it can't show whether a browser passes a setting down.
A probe MCP App in Claude desktop and VS Code that records the HostContext it receives and the media queries inside the app frame. Happy to share it.
Findings
In browsers, OS settings reach the app.prefers-contrast, prefers-reduced-motion and prefers-color-scheme match the OS inside the app frame in Chrome, Edge, WebKit and WKWebView, and update live.
Only color scheme has a host-side lever. A host can set the app's prefers-color-scheme (color-scheme on the iframe, Electron's nativeTheme.themeSource, macOS NSAppearance). There's no equivalent for contrast, motion or text size, and letting embedders override preferences for iframes is still an open question in the CSS Working Group (w3c/csswg-drafts#11577).
High-contrast host themes are invisible to apps. In VS Code, Dark and Light High Contrast produce exactly the same HostContext as normal dark and light themes. VS Code's own webview API exposes high contrast and reduced motion, so the host has the information; MCP Apps has nowhere to put it.
theme and prefers-color-scheme can disagree. VS Code sends its own editor theme as theme, but the app's prefers-color-scheme still follows the OS. With a light VS Code theme on a dark Mac, an app styled with the standard media query renders dark inside a light editor. Claude desktop keeps them in sync.
So HostContext is the one channel that works everywhere: the host knows the user's preferences, and the platform gives it no other way to tell the app.
Strawman
Optional McpUiHostContext fields with values that mirror Media Queries Level 5:
The host resolves the value from OS and host settings, as fix: remove "system" from theme options #40 settled for theme, and sends it in ui/initialize and host-context-changed.
An absent field means unknown, so apps fall back to media queries. McpUiHostContext already allows additional properties, so this is additive.
theme stays "light" | "dark"; contrast is independent of light or dark, and a separate field avoids breaking apps that switch on theme.
textScale is bucketed to limit fingerprinting, following Blink's env(preferred-text-scale).
Separately: hosts SHOULD set color-scheme on the app's iframe to match theme, which fixes finding 5 with no new API.
Happy to help with this in any way. If the shape looks right to folks, I could open a draft PR against specification/draft/apps.mdx and src/spec.types.ts (I'm not sure what the process is for this kind of stuff).
@schne324 hey there! Could you share the probe? I think a draft PR sounds like a good start (cc @liady ) - starting with prefersContrast and keeping it separate from light/dark theme - & let apps fall back to the media query when the host doesn't provide it. That way we've got somethign to test end-to-end without having to handle reduced motion or text scaling in the same pr - what do you think?
@schne324 hey there! Could you share the probe? I think a draft PR sounds like a good start (cc @liady ) - starting with prefersContrast and keeping it separate from light/dark theme - & let apps fall back to the media query when the host doesn't provide it. That way we've got somethign to test end-to-end without having to handle reduced motion or text scaling in the same pr - what do you think?
Agreed. I think there are few ways we can go but that sounds like a good start.
@schne324 please feel free to open a PR to the spec file. Please LMK if you need anything.
Activity
phillamb168 commentedon Apr 5, 2026
First, thanks for creating the issue. I'm working with the American Council of the Blind on some MCP integrations and in my discussions with them, they are VERY excited about both the current state as well as potential future state for AI generally. I've got a meeting with them tomorrow morning and I'm going to be asking about getting a pool of folks together who might be able to help with real-world a11y testing, and the people on their end I've worked with in the past on similar tasks have been quite thorough.
Anyway - quick first pass on this issue: I think we should separate what the spec can standardize from what each host must implement, and I'd like some input on the below breakdown:
Where I think we’re at now:
Things I think we need to clarify next:
Proposed path forward (before drafting spec text):
basic-host+ at least one production host.What do you think? I can also put together the initial responsibility matrix/checklist in a follow-up.
willsutton commentedon May 6, 2026
Hi @idosal — happy to see this issue. I’m head of innovation at AbilityNet (UK accessibility charity).
The host/app split in MCP Apps is a genuinely interesting accessibility surface — the rendering layer being separable from the source service creates opportunities (host can enforce semantic structure, focus patterns, AT conventions consistently) but also risks (status messages crossing the iframe boundary, focus management at sandbox edges, host conformance silence in the current spec).
I’m planning to spend some time auditing the current draft and the example apps against WCAG 2.2 AA over the coming month, and will follow up here with concrete findings.
A couple of questions in the meantime that would help shape that:
phillamb168 commentedon May 7, 2026
Hi @willsutton, I was just on a call with Jeff Bishop at ACB when I saw your comment come in, he mentioned he knows you. Your perspective on the host/app accessibility surface (and the planned WCAG 2.2 AA audit of the draft + example apps) is going to be incredibly valuable. Thank you.
Quick answers to your questions, from my perspective/opinion:
Core spec vs. profile/extension: My own take (and what I proposed a bit earlier in the thread) is that the host/app contract around accessibility should live in the core MCP Apps spec wherever we can make it host-agnostic and enforceable (focus management across iframe boundaries, status-message announcements, theming/contrast guarantees, safe-area/zoom behavior, etc.). Anything that ends up being host-specific UI patterns or deeper guidance could be non-normative appendices or a separate profile. Definitely something the WG should discuss explicitly.
Hosts to cover: basic-host is the highest-priority reference implementation. Any production hosts you’re able to test (Claude Desktop, ChatGPT, etc.) would be excellent additional data points.
Discord: There’s an active thread in the #mcp-apps-wg server called “a11y for Apps” (started ~April 4 2026). If you drop me your Discord handle I’ll add you immediately, or you can scroll back and jump in.
On the ACB side: As I said earlier, I just got off the phone with my contacts at the American Council of the Blind. Our call was mostly about broader AI adoption, but in an earlier conversation Dan (ACB president) said something that’s stuck with me and I think gives this issue real urgency: “If you get it right out of the gate we’re not a generation behind again.” They’re very excited and have already offered to pull together a pool of technical users for real-world testing once we have something stable to run against.
I’ll post an initial draft of the host/app/spec responsibility matrix and practical test checklist I mentioned earlier as a strawman/starting point for discussion. I’d love to incorporate your audit findings and coordinate with both AbilityNet and ACB folks so we’re testing against real workflows (screen readers, keyboard-only, magnification, etc.).
Let me know how you’d like to sync up and of course quite happy to facilitate any intros (sounds like you may not need them XD )
phillamb168 commentedon May 7, 2026
Initial Draft – MCP Apps Accessibility Responsibility Matrix
(Strawman / starting point based on the earlier discussion.)
focus-visible, propertabindexinside the iframerole=alert,aria-liveetc.<label>,aria-labelledby,aria-describedbyetc.aria-live,role=statusetc.willsutton commentedon May 7, 2026
@phillamb168 Thanks for the warm welcome. Discord handle is suttzz it would be great to be added to the a11y for Apps thread. I’ll read back through it before commenting.
I agree on the core-spec / non-normative-appendix split. Host-agnostic and enforceable in core, host-specific patterns as appendices or a profile, feels right.
Quick thought on the matrix as additions for WG discussion:
Cognitive accessibility as its own row. Probably the strongest opportunity the host/app split creates — the host can offer plain-language alternatives, simplification, and mode-shifting on demand, none of which retrofit that well onto traditional sites.
On the audit: spec and basic-host feel like good starting points. I’ll post findings in the Discord thread first so the WG can shape what comes back here.
AbilityNet also has an existing diverse user research capability — happy to explore coordinating with ACB when the time is right, the two together would be a strong evidence base.
liady commentedon Jun 23, 2026
On that topic - a post authored by @phillamb168 for the AAIF about the current state of agentic accessibility, including View Tools / WebMCP, etc: https://aaif.io/blog/native-speakers-why-ais-most-powerful-users-are-blind/
phillamb168 commentedon Jul 23, 2026
Sorry for the super mega delayed response... based on the feedback, I'd propose the following guiding principle:
Each layer owns accessibility for what it renders and directly controls. Behavior that crosses the host/app boundary is shared responsibility and, where interoperability is required, belongs in the spec.
Based on @willsutton 's suggestion I'd also distinguish between:
so here's an attempt at a revised matrix:
With that in mind, and trying to move towards something actionable, I'd propose the following next steps:
Unless there's disagreement with the responsibility split above, I'd suggest treating this as the working model and start moving from the matrix into that first narrow spec/test slice rather than trying to resolve every accessibility question in this thread first... thoughts?
schne324 commentedon Nov 18, 2026
I'd like to pick up the "Contrast, theming, and user preferences" row from @phillamb168's matrix, where the spec's job is to "define interoperable preference/theme signals and their semantics."
What I tested
allow-scripts) in Chrome, Edge, Firefox, WebKit, a native macOS WKWebView host and Electron, using real macOS settings (Increase Contrast, Reduce Motion). Note for anyone repeating this: Playwright'semulateMediasets the value in each Chromium frame separately, so it can't show whether a browser passes a setting down.HostContextit receives and the media queries inside the app frame. Happy to share it.Findings
prefers-contrast,prefers-reduced-motionandprefers-color-schemematch the OS inside the app frame in Chrome, Edge, WebKit and WKWebView, and update live.prefers-contrast: moreis false inside the app while macOS Increase Contrast is on, even thoughnativeTheme.shouldUseHighContrastColorsistrue.ElectronBrowserClient::OverrideWebPreferencespasses color scheme and forced colors to web content but never setspreferred_contrast. I've filed that upstream ([Bug]: prefers-contrast never matches "more" in web content, though nativeTheme.shouldUseHighContrastColors is true electron/electron#55917)prefers-color-scheme(color-schemeon the iframe, Electron'snativeTheme.themeSource, macOSNSAppearance). There's no equivalent for contrast, motion or text size, and letting embedders override preferences for iframes is still an open question in the CSS Working Group (w3c/csswg-drafts#11577).HostContextas normal dark and light themes. VS Code's own webview API exposes high contrast and reduced motion, so the host has the information; MCP Apps has nowhere to put it.themeandprefers-color-schemecan disagree. VS Code sends its own editor theme astheme, but the app'sprefers-color-schemestill follows the OS. With a light VS Code theme on a dark Mac, an app styled with the standard media query renders dark inside a light editor. Claude desktop keeps them in sync.So
HostContextis the one channel that works everywhere: the host knows the user's preferences, and the platform gives it no other way to tell the app.Strawman
Optional
McpUiHostContextfields with values that mirror Media Queries Level 5:theme, and sends it inui/initializeandhost-context-changed.McpUiHostContextalready allows additional properties, so this is additive.themestays"light" | "dark"; contrast is independent of light or dark, and a separate field avoids breaking apps that switch ontheme.textScaleis bucketed to limit fingerprinting, following Blink'senv(preferred-text-scale).Separately: hosts SHOULD set
color-schemeon the app's iframe to matchtheme, which fixes finding 5 with no new API.Happy to help with this in any way. If the shape looks right to folks, I could open a draft PR against
specification/draft/apps.mdxandsrc/spec.types.ts(I'm not sure what the process is for this kind of stuff).phillamb168 commentedon Nov 19, 2026
@schne324 hey there! Could you share the probe? I think a draft PR sounds like a good start (cc @liady ) - starting with
prefersContrastand keeping it separate from light/darktheme- & let apps fall back to the media query when the host doesn't provide it. That way we've got somethign to test end-to-end without having to handle reduced motion or text scaling in the same pr - what do you think?idosal commentedon Nov 19, 2026
Agreed. I think there are few ways we can go but that sounds like a good start.
@schne324 please feel free to open a PR to the spec file. Please LMK if you need anything.