MCP server best practices

The Figma MCP server gives your agent structured context from your Figma files. The quality of what your agent builds depends on that context and on how you ask. Use these best practices to get clearer, more consistent code that fits your design system and codebase.

• Structure your Figma file
• Write effective prompts
• Name specific tools when needed
• Add custom rules and instructions
• Work with smaller selections

Structure your Figma file

A well-structured file tells your agent what each part of the design is and how it should behave.

• Use components. Make anything that repeats, like buttons, cards, inputs, and nav items, a component. This keeps the file clean and lets your agent reuse the same code for each instance.
• Connect components to code with Code Connect. This is the most effective way to get your agent to reuse your real components. Without it, your agent has to guess which code component matches.
• Use variables for spacing, color, corner radius, and typography, so your agent can reference your tokens instead of hardcoded values.
• Give layers and components clear names. Replace default names like Frame1268 or Group5 with names that describe their purpose, like CardContainer, ProductImage, or CTA_Button. This helps your agent understand what each layer is and how it should work.
• Use auto layout. Auto layout shows how your design should respond to different sizes and avoids absolute positioning, which usually leads to cleaner, more predictable code. Before generating code, resize the frame to check that it behaves the way you expect.
• Add annotations to explain things that are hard to show visually, like how an element should behave, align, or respond.
• Add dev resources to layers in Dev Mode, so your agent gets links to related documentation, code, or tickets.

Write effective prompts

The MCP server gives your agent the design data, but what your agent does with it depends on what you ask. Write your prompt like you're briefing a teammate: the more specific you are, the better the result.

A good prompt can tell your agent to:

• Use a specific framework or styling system
• Follow your codebase conventions, like file structure, naming, and layout
• Put code in the right place, like src/pages or components/ui
• Add to or change existing files instead of creating new ones
• Use a specific layout system, like flexbox, grid, or absolute positioning

Example prompts:

• "Generate iOS SwiftUI code from the selected Figma frame."
• "Implement the selected frame using Chakra UI components."
• "Generate this using components from src/components/ui."
• "Add this component to src/components/marketing/PricingCard.tsx."
• "Implement this using our Stack layout component."

Name specific tools when needed

Each MCP server tool gives your agent a different kind of context. Your agent usually chooses the right one, but not always, especially as more tools become available. If the output seems off or incomplete, try naming the tool or describing exactly what you want.

For example:

• get_design_context returns a structured representation of your selection, in React and Tailwind by default. Your agent can translate it into any framework or code style you ask for.
• get_variable_defs returns the variables and styles used in your selection, such as color, spacing, and typography, so your agent can use your tokens directly.

Some people asking for variable values got code instead. Rephrasing the prompt to "Get the variable names and values used in this frame" made the intent clear, and the agent used the right tool.

Add custom rules and instructions

Rules are project-level instructions your agent follows every time. Use them for the unwritten rules of your codebase that an experienced developer would pass on to a new teammate, like:

• Which layout components to use
• Where component files belong
• How components should be named
• What should never be hardcoded

Adding rules once means less repeated prompting, and everyone on your team, human or agent, follows the same expectations. Check your MCP client's documentation for where rules go and how to format them, then experiment to find what works for your team.

General rules

Start with general rules like these:

- IMPORTANT: Always use components from `/path_to_your_design_system` when possible
- Prioritize Figma fidelity to match designs exactly
- Avoid hardcoded values, use design tokens from Figma where available
- Follow WCAG requirements for accessibility
- Add component documentation
- Place UI components in `/path_to_your_design_system`; avoid inline styles unless truly necessary

Rules for consistent output

These rules tell your agent how to use the Figma MCP server step by step:

## Figma MCP Integration Rules
These rules define how to translate Figma inputs into code for this project and must be followed for every Figma-driven change.

### Required flow (do not skip)
1. Run get_design_context first to fetch the structured representation for the exact node(s).
2. If the response is too large or truncated, run get_metadata to get the high-level node map and then re-fetch only the required node(s) with get_design_context.
3. Run get_screenshot for a visual reference of the node variant being implemented.
4. Only after you have both get_design_context and get_screenshot, download any assets needed and start implementation.
5. Translate the output (usually React + Tailwind) into this project's conventions, styles and framework. Reuse the project's color tokens, components, and typography wherever possible.
6. Validate against Figma for 1:1 look and behavior before marking complete.

### Implementation rules
- Treat the Figma MCP output (React + Tailwind) as a representation of design and behavior, not as final code style.
- Replace Tailwind utility classes with the project's preferred utilities/design-system tokens when applicable.
- Reuse existing components (e.g., buttons, inputs, typography, icon wrappers) instead of duplicating functionality.
- Use the project's color system, typography scale, and spacing tokens consistently.
- Respect existing routing, state management, and data-fetch patterns already adopted in the repo.
- Strive for 1:1 visual parity with the Figma design. When conflicts arise, prefer design-system tokens and adjust spacing or sizes minimally to match visuals.
- Validate the final UI against the Figma screenshot for both look and behavior.

Rules for assets

When the desktop server is set to serve images from a local server, it returns localhost links for images and SVGs. These rules tell your agent to use those links instead of placeholders or new icon packages.

In Cursor, add the rules to a rule file in your project's .cursor/rules folder:

---
description: Figma MCP server rules
globs:
alwaysApply: true
---
  - The Figma MCP server provides an assets endpoint which can serve image and SVG assets
  - IMPORTANT: If the Figma MCP server returns a localhost source for an image or an SVG, use that image or SVG source directly
  - IMPORTANT: DO NOT import/add new icon packages, all the assets should be in the Figma payload
  - IMPORTANT: do NOT use or create placeholders if a localhost source is provided

In Claude Code, add them to your CLAUDE.md file:

# MCP Servers
## Figma MCP server rules
  - The Figma MCP server provides an assets endpoint which can serve image and SVG assets
  - IMPORTANT: If the Figma MCP server returns a localhost source for an image or an SVG, use that image or SVG source directly
  - IMPORTANT: DO NOT import/add new icon packages, all the assets should be in the Figma payload
  - IMPORTANT: do NOT use or create placeholders if a localhost source is provided

Generate your own rules

You can also ask your agent to write rules for you. Use a prompt like this:

Please analyze this codebase thoroughly and provide a comprehensive rules doc for your use (e.g. CLAUDE.md) on the following aspects to help integrate Figma designs using the Model Context Protocol:

## Design System Structure

1. **Token Definitions**
   - Where are design tokens (colors, typography, spacing, etc.) defined?
   - What format/structure is used for tokens?
   - Are there any token transformation systems in place?

2. **Component Library**
   - Where are UI components defined?
   - What component architecture is used?
   - Are there any component documentation or storybooks?

3. **Frameworks & Libraries**
   - What UI frameworks are used (React, Vue, etc.)?
   - What styling libraries/frameworks are used?
   - What build system and bundler are used?

4. **Asset Management**
   - How are assets (images, videos, etc.) stored and referenced?
   - What asset optimization techniques are used?
   - Are there any CDN configurations?

5. **Icon System**
   - Where are icons stored?
   - How are icons imported and used in components?
   - Is there an icon naming convention?

6. **Styling Approach**
   - What CSS methodology is used (CSS Modules, Styled Components, etc.)?
   - Are there global styles?
   - How are responsive designs implemented?

7. **Project Structure**
   - What is the overall organization of the codebase?
   - Are there any specific patterns for feature organization?

Provide your analysis as structured markdown with code snippets demonstrating key patterns. Include file paths where relevant.

Work with smaller selections

Large selections can slow down the tools, cause errors, or return incomplete results when there's too much context for your agent to process. For faster, more reliable results:

• Generate code for smaller sections or individual components, like a card, header, or sidebar.
• If things seem slow or stuck, select less and try again.

If you need to work with a large design, your agent can use get_metadata to get a lightweight outline first, then get design context for only the parts it needs.

If results still aren't right

Go back to the basics: how your Figma file is structured, how your prompt is written, and what context your agent is getting. Small changes in any of these often lead to more consistent, reusable code.