If you haven’t built and connected an MCP App yet, see Get started with MCP Apps.
Design for the conversation
Design your app as an extension of the conversation rather than a separate app that appears alongside it. Your app helps users accomplish meaningful tasks without breaking flow. These principles follow from that:- Conversational: fit naturally into dialogue, and don’t force users to learn new interaction patterns
- Contextual: use the arguments that Claude passes to your tool to inform what you display and when
- Integrated: inherit styling and conventions from the containing environment
- Adaptive: handle variable sizing, mobile viewports, and diverse accessibility needs gracefully
Choose what to build as an MCP App
An MCP App works best for a task the user can finish inside the conversation. Good candidates include:- Tasks that fit naturally into conversation, like data analysis, document review, or project coordination
- Communication and collaboration context, like message search results, conversation threads, or team member profiles
- Tasks with a clear start and end, like booking, ordering, or scheduling
- Information users can act on immediately
- Functionality that extends Claude’s capabilities meaningfully
- Long-form or static content better suited for external viewing
- Complex multi-step workflows that exceed the display mode’s scope
- Deep navigation such as drill-ins, breadcrumbs, or multiple views
- Nested scrolling, because inline cards should auto-fit content height
- Menus and popovers: dropdowns, context menus, and popover panels can get clipped by container boundaries or create z-index conflicts with the host UI, so prefer visible controls like segmented buttons, toggles, or inline options
- Chat inputs or conversational UI that replicate Claude’s own features
Display modes
The side panel is available to a limited set of organizations, and not in every conversation. Where it isn’t available, a fullscreen request opens your app full screen if Claude offers that mode. To check, see Show your MCP App in the side panel or full screen.
Inline card
An inline card is a compact component embedded directly in the conversation. Keep it focused. Use an inline card for:- Status updates and confirmations
- Simple data displays or selections
- Brief summaries with optional expansion
- Quick actions that continue the conversation


- Height auto-fits to content, with no nested scrolling
- At most 2 actions, placed at the bottom of the card
- At most 4-5 data points
- No drill-ins, breadcrumbs, or multiple views
- No menus or popovers, only visible controls

Inline carousel
An inline carousel shows items side by side for browsing options. Users swipe or scroll horizontally to explore. Use an inline carousel for:- Product listings or search results
- Location or venue options
- Media galleries
- Any set of comparable items

- 3-8 items for scannability
- Each card has an image, a title, up to 3 lines of metadata, and an optional CTA
- 1 optional CTA per card
- Consistent card dimensions within a carousel
- Consistent visual hierarchy across cards

Side panel
The side panel keeps your app open beside the conversation on web and desktop, so users can keep chatting while they watch the app update. Use the side panel for:- Documents, boards, and maps that the user and Claude work on together
- Results the user refers to while they ask follow-up questions
- Editors and previews that change as the conversation goes on
- The panel opens at about half the width of the chat area, and users can resize it down to about 320px
- Your app reads the
fullscreendisplay mode in the panel, as it does in full screen, so lay out by the container’s size rather than by the mode - Icon buttons in the panel’s title bar take users on to full screen or back to the conversation
Full screen
Full screen mode gives complex interactions an immersive interface. The conversation composer remains available, so users can continue talking to your app through Claude. Use full screen for:- Data visualizations and dashboards
- Detailed analysis tools
- Document editing
- Content that benefits from focused attention
- Rich tasks requiring more space than inline allows


- Your app provides its own fullscreen button, and a close button appears in the native header bar
- Where the side panel is available, Claude also shows its own expand button above an inline app that supports
fullscreenon web and desktop - A fullscreen request from your app opens the side panel where there is one, and users go on to full screen from the panel
- The composer is always visible, so design your UX to work with it
- No floating panels, so use collapsible sidebars, tabs, or pagination to disclose details

Mobile guidelines
MCP Apps on mobile follow the same principles as on web, but the constrained viewport and touch-based interaction require specific adaptations. On mobile, Claude renders apps in a native WebView,WKWebView on iOS and WebView on Android.
On Android, apps have no camera, microphone, or location access. On iOS, an app that requests the camera or the microphone in _meta.ui.permissions can use it after the user allows it. A view that Claude allows to embed a site can’t use either. Claude on mobile doesn’t report these features in app.getHostCapabilities()?.sandbox?.permissions, so call the browser API, such as getUserMedia(), without checking that field, and handle a refusal.
Host context for layout
The host passes layout hints to your app throughhostContext. Apps always fill the container width, with no fixed breakpoints, so design responsively from 320px up to fullscreen using container queries and the hostContext CSS variables.
Safe areas
Render the interactive portion of your app inside the safe area so the mobile navigation bar and chat input don’t obscure it and it respects the chat screen’s content margins. The user can’t interact with anything rendered outside the safe area, such as a button under the mobile navigation bar. ReadhostContext.safeAreaInsets.{top, right, bottom, left}, which are pixel values, and apply them as padding on your root container, or as scroll-padding on scroll-snap containers so items come to rest inside the visible region. Safe areas aren’t mobile-specific: on web and desktop the composer can overlay the bottom of an inline app, so avoid placing interactive controls flush against any edge.

Borderless inline content
Set_meta.ui.prefersBorder to true or false to control whether your content renders with a border. If you don’t set it, content renders borderless on web and bordered on mobile.
In borderless mode your content runs edge-to-edge with no host padding, so honoring safeAreaInsets becomes essential. The bordered card’s built-in padding otherwise absorbs most of them. Borderless works well for carousels and other horizontally scrolling content that should bleed to the screen edges while in motion: apply safeAreaInsets.left and .right as scroll-padding-inline on the scroll container so items at rest sit clear of the device edges but can scroll underneath them.

Declare supported display modes
Declare which modes your app supports throughappCapabilities.availableDisplayModes in ui/initialize. The host responds with the modes it supports, and your app can request a switch with ui/request-display-mode. Claude offers inline and fullscreen. For the request, its result, and the size that Claude reports, see Show your MCP App in the side panel or full screen.
Content security policy
All external origins are blocked by default. Declare the origins eachui:// resource needs through _meta.ui.csp:
connectDomains: origins your app reaches withfetch,XMLHttpRequest, or a WebSocketresourceDomains: origins your app loads scripts, styles, images, fonts, media, and web workers fromframeDomains: origins your app embeds in an<iframe>. Claude also has to allow these origins for your connector, as Embed a website in an MCP App explains.
https:// or wss://. In connectDomains and resourceDomains, Claude drops an entry it can’t read and applies the rest. A request to a dropped origin fails with a Content Security Policy error in the browser console. If you set baseUriDomains, Claude ignores it and keeps the base URI on your app’s own origin.
Viewport and layout
- Design for variable widths, from a 320pt minimum up to tablet
- Respect safe areas on notched devices
- Use full-width layouts, without side margins that waste mobile screen space
- Let content reflow gracefully, and avoid fixed-width layouts

Touch targets
- Minimum tap target of 44 x 44pt, per the Apple HIG and Material guidelines
- Sufficient spacing between interactive elements to prevent mis-taps
- Larger, thumb-friendly buttons rather than small text links
- Primary actions within natural thumb reach, in the lower portion of the screen

Scrolling and gestures
On mobile touch devices, the conversation view owns vertical scrolling. When your app is rendered inline, vertical pan gestures that start inside it go to the conversation scroll instead of to your content, so a tall widget can’t trap the user. The host also caps inline height and clips content that exceeds it, so fit your inline app to its content height rather than relying on an internal vertical scroll container. Horizontal gestures, such as swiping a carousel or panning a map, and taps work normally. If your app needs its own vertically scrollable viewport, request fullscreen presentation withui/request-display-mode instead of rendering inline, as described in Full screen.
Transitions
- Inline cards expand to fullscreen with a smooth transition
- Provide a clear visual affordance for expansion, such as a fullscreen button or tap-to-expand
- Closing fullscreen returns to the conversation at the same scroll position

Dark mode
All views must support both light and dark themes. Use the host’s style tokens, which adapt automatically, and never hardcode colors. Test both modes.
Loading states
Show skeleton screens while content loads, and match the layout structure of the final content so the swap is smooth. Avoid spinners for inline content, because skeletons feel more native.
Visual design
MCP Apps should feel native to their environment while maintaining consistent visual hierarchy and accessibility standards. You can still express your brand through accent colors, custom controls, and content.Color
Use host tokens for all structural elements: backgrounds, text, borders, and icons. You can use your own brand colors for accents and identity, but the core UI should use the provided palette.
Typography
Stick to the three-level size scale of heading, body, and caption, and the two weights of regular and emphasized. This creates clear hierarchy without visual noise.
The Figma Community File uses Anthropic Sans and Anthropic Serif. When your app runs inside Claude, the host client provides Anthropic Sans at runtime through style variables. For local development, download and install the fonts.
Borders
Use a limited set of corner radii and border thicknesses to keep your app feeling native to the surrounding UI.
Icons
Use monochromatic, outlined icons that match the host’s icon color tokens. Icons should support understanding rather than be essential to it.
Declare an app icon for Claude
Claude can show an icon of your own for an MCP App, in place of your connector’s icon or your listing’s logo. The icon can appear in the title bar over a view in the side panel and in full screen. Where the app has an entry point, the icon can also appear on the app’s tile on the Artifacts page. Declared icons aren’t available in every organization or conversation. Declare the icon in theicons list of your server’s serverInfo, as an inline data: URI:
initialize result then holds the icon in serverInfo.icons.
These have to hold:
- Source: an inline
data:URI insrc. Claude doesn’t fetch an icon from a URL. Anhttps:entry for other clients can stay in the list, after the inline one - Format:
data:image/png;base64,ordata:image/jpeg;base64,. Claude removes an inline SVG entry fromserverInfo - Size: keep the icon to 64 to 128 px and under 10 KB. Declare one inline icon in
serverInfo, where the whole object, icons included, can take about 16,000 characters of JSON. Beyond that, Claude drops all of it - Connector: the connector has a Verified listing, or it’s a custom connector whose address matches no directory listing
- Names: the tool’s title, and a custom connector’s name, leave out Claude’s name and Anthropic’s name
icons list to the tool that opens the app, in your server’s tools/list result. Claude uses the tool’s icon before the server’s. To check that the field is there, list your server’s tools.
Version 1 of the TypeScript SDK (@modelcontextprotocol/sdk), which the quickstart uses, doesn’t send a tool’s icons through registerTool or registerAppTool. With it, use serverInfo, which gives all your apps one icon, or answer tools/list yourself. Version 2 (@modelcontextprotocol/server) sends them through registerTool, and through registerAppTool in JavaScript.
Spacing
Maintain generous padding and logical groupings. Balance information density with readability, adapting to viewport constraints.Accessibility
Your app must be usable by everyone. Maintain high contrast at WCAG AA minimum, support keyboard navigation, and provide text alternatives for visual content. Test with assistive technologies.Interaction patterns
Some interactions belong inside your app and others belong in Claude’s chat input. Drawing that boundary correctly, revealing complexity progressively, and keeping controls visible make your app feel cohesive with the conversation.Decide between app and chat interactions
Handle these within your app:- Direct manipulation like sliders, toggles, and selections
- Filtering or sorting data you’re already displaying
- Expanding and collapsing content sections
- Confirming or executing a prepared action, such as “Mark complete,” “Send,” or “Save”
- Interacting with visualizations, like hover states or clicking data points
- Text entry and freeform input
- Follow-up questions or requests for clarification
- Requests to modify, refine, or redo something
- Navigation to different contexts or topics
- Anything that benefits from Claude’s interpretation
Reveal complexity progressively
Reveal complexity only when users need it. The inline card might show a summary, and fullscreen mode can offer the detailed view.Prefer visible controls over hidden menus
Prefer controls with visible options, such as segmented buttons, toggle chips, and inline tabs, over menus and dropdowns. Menus conflict with the host container and are harder to use on mobile.Style variables
MCP Apps automatically receive style variables from the host client. Reference these CSS custom properties to create interfaces that feel native to Claude. Blend your MCP App with Claude’s theme shows how to apply them at runtime.Color tokens
Color tokens cover backgrounds, text, and borders, and semantic accent colors signal status. All tokens automatically adapt to light and dark mode.Typography tokens
Typography tokens include the font family, sizes, weights, and line heights.Radius tokens
Radius tokens provide border radius values.Border width tokens
Border width tokens provide border width values.Shadow tokens
Shadow tokens provide drop-shadow values.Example usage
This CSS applies the host tokens to an app container, a card, and a button:Related resources
- Blend your MCP App with Claude’s theme: apply the style variables and keep your background transparent
- Set
ui.domainfor Claude: compute the sandbox origin Claude expects for your app - Submit a connector: screenshot specifications for listing an MCP App in the directory