Skip to content

Accessibility #431

Open
Open

Description

@idosal

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.

Activity

  1. self-assigned this
    on Feb 5, 2026
  2. phillamb168 commented on Apr 5, 2026

    @phillamb168

    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?

    Proposed path forward (before drafting spec text):

    1. Create a host/app/spec responsibility matrix for key accessibility areas (keyboard/focus, SR support, labeling, contrast/theming, zoom/magnification).
    2. Turn that matrix into a practical test checklist we can run across basic-host + at least one production host.
    3. Use those findings to decide:
      • doc-only guidance,
      • normative spec clarifications,
      • or protocol additions (if any gaps can’t be solved with current hooks).
    4. 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.

  3. willsutton commented on May 6, 2026

    @willsutton

    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:

    1. Is the intent for accessibility to live as part of the core MCP Apps spec, or as a profile/extension on top?
    2. Are there host implementations you’d specifically like the audit to cover beyond basic-host?
    3. Has the WG discussed accessibility informally on Discord that I should catch up on before commenting further?
  4. phillamb168 commented on May 7, 2026

    @phillamb168

    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:

    1. 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.

    2. 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.

    3. 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 )

  5. phillamb168 commented on May 7, 2026

    @phillamb168

    Initial Draft – MCP Apps Accessibility Responsibility Matrix
    (Strawman / starting point based on the earlier discussion.)

    Accessibility Area Spec (normative) Host Responsibilities App Responsibilities Testing / Notes
    Keyboard / Focus Management Define focus delegation, trapping, and boundary behavior across iframe Consistent focus styles, handle entry/exit from iframe, respect system focus preferences Logical tab order, focus-visible, proper tabindex inside the iframe WCAG 2.4.3, 2.4.7; test keyboard-only
    Screen Reader Support & Announcements Requirements for live regions / status messages to cross boundary Expose proper roles/ARIA to AT; handle iframe semantics Semantic HTML, ARIA labels/roles, role=alert, aria-live etc. WCAG 4.1.3; test with NVDA + VoiceOver
    Labeling & Semantic Structure Expectations for accessible names/descriptions — Proper <label>, aria-labelledby, aria-describedby etc. WCAG 4.1.2
    Theming / Contrast / High-Contrast Require host theming tokens (light/dark/high-contrast) Supply tokens, respect system preferences Use tokens, ensure minimum contrast ratios WCAG 1.4.3 / 1.4.6
    Zoom / Reflow / Magnification Requirements for reflow at 200% / 400% zoom Support viewport resizing and safe-area insets Responsive layout that reflows without loss of content/function WCAG 1.4.4, 1.4.10
    Status Messages / Dynamic Updates Protocol for host to surface app announcements Route announcements across iframe boundary Use aria-live, role=status etc. WCAG 4.1.3
  6. willsutton commented on May 7, 2026

    @willsutton

    @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.

  7. self-assigned this
    on Jun 20, 2026
  8. liady commented on Jun 23, 2026

    @liady
    Contributor

    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/

  9. phillamb168 commented on Jul 23, 2026

    @phillamb168

    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:

    • normative core requirements (host-agnostic, interoperable, testable/enforceable)
    • non-normative guidance (host-specific implementation patterns & recommended UX approach)

    so here's an attempt at a revised matrix:

    Area App responsibility Host responsibility Spec responsibility
    Keyboard operability 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:

    1. 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.
    2. Move app-only and host-only findings out of this issue into example/docs/guidance work as appropriate.
    3. Turn the first clear Boundary/Spec findings into a small draft spec PR, rather than waiting for the entire audit to be complete.
    4. 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.
    5. 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?

  10. schne324 commented on Nov 18, 2026

    @schne324

    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

    1. 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.
    2. Electron hosts drop contrast. In Electron, Claude desktop and VS Code, prefers-contrast: more is false inside the app while macOS Increase Contrast is on, even though nativeTheme.shouldUseHighContrastColors is true. ElectronBrowserClient::OverrideWebPreferences passes color scheme and forced colors to web content but never sets preferred_contrast. I've filed that upstream ([Bug]: prefers-contrast never matches "more" in web content, though nativeTheme.shouldUseHighContrastColors is true electron/electron#55917)
    3. 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).
    4. 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.
    5. 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:

    prefersContrast?: "no-preference" | "more" | "less" | "custom";
    prefersReducedMotion?: "no-preference" | "reduce";
    textScale?: number; // relative to host default, coarsely bucketed
    • 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).

  11. phillamb168 commented on Nov 19, 2026

    @phillamb168

    @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?

  12. idosal commented on Nov 19, 2026

    @idosal
    ContributorAuthor

    @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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions