Design guidelines

Overview

MCP Apps are interactive interfaces that appear within Claude’s conversational flow. Think of them as natural extensions of the conversation, not separate apps that happen to appear alongside it. Your app inherits conversational context and helps users accomplish meaningful tasks without breaking flow. Core principles:

Conversational. Fit naturally into dialogue. Don’t force users to learn new interaction patterns.
Contextual. Use conversation history 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.

See our Figma UI kit for components and patterns to help you get started.

What makes a good MCP App

Good candidates:

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

Patterns to avoid:

Long-form or static content better suited for external viewing (max 500px height)
Complex multi-step workflows that exceed the display mode’s scope
Deep navigation (no drill-ins, breadcrumbs, or multiple views)
Nested scrolling (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 — prefer visible controls like segmented buttons, toggles, or inline options)
Chat inputs or conversational UI (don’t replicate Claude’s features)

Display modes

Inline card

Compact components embedded directly in conversation. These work well for summaries, confirmations, and quick actions. Keep them focused: four to five data points maximum, one primary action. Good uses:

Status updates and confirmations
Simple data displays or selections
Brief summaries with optional expansion
Quick actions that continue the conversation

Inline card example showing a compact component

Inline card example showing a data display

Fullscreen

Immersive interfaces for complex interactions. The conversation composer remains available so users can continue talking to your app through Claude. Apps provide their own fullscreen button. A close button appears in the native header bar when in fullscreen mode. In fullscreen mode, avoid the use of floating panels. Use collapsible sidebars, tabs or pagination to disclose details. Good uses:

Data visualizations and dashboards
Detailed analysis tools
Document editing
Content that benefits from focused attention

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. Design guidance Color. Use host tokens for all structural elements: backgrounds, text, borders, icons. You can use your own brand colors for accents and identity, but the core UI should use the provided palette.

Color token examples for light and dark mode

Typography. Stick to the three-level size scale (heading, body, caption) and two weights (regular, 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. Download and install the fonts from here for local development.

Borders. Using a limited set of corner radii and thickness will 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, not be essential to it.

Spacing. Maintain generous padding and logical groupings. Balance information density with readability, adapting to viewport constraints.

Interaction patterns

App vs. chat interactions

Understanding the boundary between your app’s interactions and Claude’s conversational interface helps you build something that feels cohesive. Handle 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 (“Mark complete,” “Send,” “Save”)
Interacting with visualizations like hover states or clicking data points

Prefer controls with visible options (segmented buttons, toggle chips, inline tabs) over menus and dropdowns, which can conflict with the host container. Push to chat input:

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

If the interaction requires language understanding or generates a response from Claude, it goes through chat. If it’s a direct UI action on content your app already controls, handle it in the app.

Start simple

Reveal complexity only when users need it. The inline card might show a summary; fullscreen mode can offer the detailed view.

Accessibility

Maintain high contrast standards (WCAG AA minimum). Support keyboard navigation and provide text alternatives for visual content. Test with assistive technologies. Your app must be usable by everyone.

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. Color tokens cover backgrounds, text, and borders. Semantic accent colors signal status. All tokens automatically adapt to light and dark mode.

	Light mode	Dark mode
Background
`color-background-primary`	`#FFFFFF`	`#30302E`
`color-background-secondary`	`#F5F4ED`	`#262624`
`color-background-tertiary`	`#FAF9F5`	`#141413`
`color-background-inverse`	`#141413`	`#FAF9F5`
`color-background-ghost`	`#FFFFFF (0%)`	`#30302E (0%)`
`color-background-info`	`#D6E4F6`	`#253E5F`
`color-background-danger`	`#B53333`	`#DD5353`
`color-background-success`	`#E9F1DC`	`#1B4614`
`color-background-warning`	`#F6EEDF`	`#483A0F`
`color-background-disabled`	`#FFFFFF (50%)`	`#30302E (50%)`
Text
`color-text-primary`	`#141413`	`#FAF9F5`
`color-text-secondary`	`#3D3D3A`	`#C2C0B6`
`color-text-tertiary`	`#73726C`	`#9C9A92`
`color-text-inverse`	`#FFFFFF`	`#141413`
`color-text-ghost`	`#73726C (50%)`	`#9C9A92 (50%)`
`color-text-info`	`#3266AD`	`#80AADD`
`color-text-danger`	`#7F2C28`	`#EE8884`
`color-text-success`	`#265B19`	`#7AB948`
`color-text-warning`	`#5A4815`	`#D1A041`
`color-text-disabled`	`#141413 (50%)`	`#FAF9F5 (50%)`
Border
`color-border-primary`	`#1F1E1D (40%)`	`#DEDCD1 (40%)`
`color-border-secondary`	`#1F1E1D (30%)`	`#DEDCD1 (30%)`
`color-border-tertiary`	`#1F1E1D (15%)`	`#DEDCD1 (15%)`
`color-border-inverse`	`#FFFFFF (30%)`	`#141413 (15%)`
`color-border-ghost`	`#1F1E1D (0%)`	`#DEDCD1 (0%)`
`color-border-info`	`#4682D5`	`#4682D5`
`color-border-danger`	`#A73D39`	`#CD5C58`
`color-border-success`	`#437426`	`#599130`
`color-border-warning`	`#805C1F`	`#A87829`
`color-border-disabled`	`#1F1E1D (10%)`	`#DEDCD1 (10%)`
Ring
`color-ring-primary`	`#141413 (70%)`	`#FAF9F5 (70%)`
`color-ring-secondary`	`#3D3D3A (70%)`	`#C2C0B6 (70%)`
`color-ring-inverse`	`#FFFFFF (70%)`	`#141413 (70%)`
`color-ring-info`	`#3266AD (50%)`	`#80AADD (50%)`
`color-ring-danger`	`#A73D39 (50%)`	`#CD5C58 (50%)`
`color-border-success`	`#437426 (50%)`	`#599130 (50%)`
`color-border-warning`	`#805C1F (50%)`	`#A87829 (50%)`

Typography tokens include the font family, sizes, weights and line heights.

Family
`font-sans`	`“Anthropic Sans, sans-serif”`
`font-mono`	`“ui-monospace, monospace”`
Weight
`font-weight-normal`	`400`
`font-weight-medium`	`500`
`font-weight-semibold`	`600`
`font-weight-bold`	`700`
Size
`font-text-xs-size`	`12px`
`font-text-sm-size`	`14px`
`font-text-md-size`	`16px`
`font-text-lg-size`	`20px`
`font-heading-xs-size`	`12px`
`font-heading-sm-size`	`14px`
`font-heading-md-size`	`16px`
`font-heading-lg-size`	`20px`
`font-heading-xl-size`	`24px`
`font-heading-2xl-size`	`28px`
`font-heading-3xl-size`	`36px`
Line-height
`font-text-xs-line-height`	`1.4`
`font-text-sm-line-height`	`1.4`
`font-text-md-line-height`	`1.4`
`font-text-lg-line-height`	`1.25`
`font-heading-xs-line-height`	`1.4`
`font-heading-sm-line-height`	`1.4`
`font-heading-md-line-height`	`1.4`
`font-heading-lg-line-height`	`1.25`
`font-heading-xl-line-height`	`1.25`
`font-heading-2xl-line-height`	`1.1`
`font-heading-3xl-line-height`	`1`

Radius tokens provide border radius values

Radius
`border-radius-xs`	`4px`
`border-radius-sm`	`6px`
`border-radius-md`	`8px`
`border-radius-lg`	`10px`
`border-radius-xl`	`12px`
`border-radius-full`	`9999px`

Border width tokens provide width values


`border-width-regular`	`0.5px`

Example usage

.my-app {
  background: var(--color-background-primary);
  color: var(--color-text-primary);
  font: var(--font-style-body);
}

.card {
  background: var(--color-background-secondary);
  border-color: var(--color-border-primary);
  border-width: var(--border-width-regular);
  border-radius: var(--border-radius-medium);
}

.button {
  background: var(--color-background-inverse);
  color: var(--color-text-inverse);
  font: var(--font-style-body-emphasized);
  border-radius: var(--border-radius-medium);
}

Third-party Connectors

Building Connectors

Built-in Integrations

Overview

What makes a good MCP App