What an agent actually “sees” on a canvas
Figma’s MCP server, by its own documentation, “gives AI agents the design context they need to generate code from your Figma files, and lets agents write native Figma content back to the canvas” (Figma MCP docs). That phrasing is more precise than it looks: the agent receives context the server assembles, never the canvas itself.
A spatial canvas of frames and layers is a visual object for the human designer; for an agent it exists only as whatever representation a tool’s API assembles on request — code in a chosen framework, an outline of names and coordinates, a token list, or a bitmap. Each format preserves some semantics and discards the rest, so “what can an agent perceive on a canvas” is really a tooling question: which endpoint, with what arguments, returning what format. This post reads the two most documented answers, Figma’s MCP server and Penpot’s MCP setup, tool by tool.
The read tools: what each call returns to the agent
Figma’s main read tool, get_design_context, returns design context and code for a layer or selection, with React and Tailwind as the default output and other frameworks on request, per Figma MCP tools and prompts. Four of the read tools cover metadata, variables, screenshots, and design-system search.
get_design_context— the main tool: design context and code for a layer or selection, React and Tailwind by default.get_metadata— a lightweight XML outline with basic properties only: layer IDs, names, types, positions, sizes. Without a node ID it returns the file’s top-level pages, which lets an agent choose where to look.get_variable_defs— the variables and styles used in the selection: colors, spacing, typography.get_screenshot— a screenshot of the selection.search_design_system— a text search over connected libraries for components, variables, and styles.
As perception channels they trade off sharply: code is design intent already translated into a framework; the XML outline is structure without styling intent; variables are the token layer alone; a screenshot is appearance with nothing to compute on; library search returns definitions, not the current selection’s contents.
Context reaches the server through links, not file access. The user right-clicks a frame and selects “Copy link to selection,” and the client extracts the node ID; the client does not open the link itself (Figma MCP docs). Figma’s “Code to canvas with your design system” case study describes the design side of the same flow: annotations on a frame “live right on the design, the AI agents can pull important design context right from the source” (Figma Help Center).
Which tool runs is usually the agent’s choice, “but not always” the right one. Figma’s trigger-specific-tools page records it plainly: “Some people asking for variable values got code instead.” Rephrasing the prompt to “Get the variable names and values used in this frame” fixed the selection (Figma trigger-specific tools).
| Tool | What the agent gets back | Where the signal breaks |
|---|---|---|
get_design_context |
Design context and code for a layer or selection; React and Tailwind by default | A framework translation, not the node tree; representation of auto-layout, constraints, or z-order is undocumented |
get_metadata |
Lightweight XML outline: layer IDs, names, types, positions, sizes | Structure without styling intent — basic properties only |
get_variable_defs |
Variables and styles used in the selection: colors, spacing, typography | The token layer only, and only if the agent picks this tool over get_design_context |
get_screenshot |
A screenshot of the selection | Pixels without semantics — nothing to compute on |
search_design_system |
Text-query matches from connected libraries: components, variables, styles | Library-scoped; finds definitions, not what the selection contains |
The write tool: use_figma and its limits
use_figma runs code in the Figma file through the Figma Plugin API and creates and updates frames, components, variants, variables, and auto layout, “rather than a screenshot or static export,” per Figma write-to-canvas docs. It is the documented path for an agent to place native content on the canvas.
The documented limitations, verbatim from the write-to-canvas page:
- Each tool call can return up to 20 KB of output.
use_figmacannot add new images on its own; the agent usesupload_assetsorgenerate_image.- Fonts must be uploaded to the Figma account — fonts only installed locally are unavailable.
- Components must be published manually before Code Connect mappings.
- “Output is beta quality and may need manual review and cleanup.”
Access is gated. Write-to-canvas requires the remote server and edit access, and is available on Professional, Education, Organization, and Enterprise plans; Figma says it is “free to use during the beta period. It will eventually become a usage-based paid feature.” The recommended remote endpoint is mcp.figma.com/mcp, which needs no desktop app (Figma’s setup guide). A desktop server also runs through the Figma desktop app, but that path requires a Dev or Full seat on Professional, Education, Organization, Government, or Enterprise plans. Clients listed for remote-with-write include Claude Code, Cursor, VS Code, Codex, and OpenCode (Figma MCP docs).
The dedicated read tools return pre-packed slices, but use_figma is general-purpose: the tools page says it can “create, edit, delete, or inspect content,” and the get_metadata page points an agent to it for per-page child counts and top-level node types. An agent that needs raw structure therefore has a second route. Figma’s advice to test on a duplicate of your library or a draft file before changing production files applies to that route too (Figma write-to-canvas docs).
The Penpot contrast: a different architecture for the same job
Penpot’s MCP setup has three pieces: an MCP server exposing tools to the AI client, an MCP plugin running inside Penpot that connects the open file to the server, and the MCP client, such as Cursor or Claude Code (Penpot MCP help). A personal MCP key, one per user at a time, serves the remote setup.
Scoping follows the user, not the file. The server “can access the currently focused page”: MCP always operates on the page in focus, and if the user changes pages, the MCP context follows. It can be active in only one browser tab at a time, and the user chooses which tab owns it (Penpot MCP help).
The documented tool surface includes execute_code, high_level_overview, penpot_api_info, export_shape, and import_image. In remote mode the help page lists two limits: import_image cannot read local file paths, and export_shape is limited, with no direct export to local file paths. Documented uses include reading and modifying file structure (components, styles, tokens, pages, layers), generating HTML/CSS, and auditing design-system consistency, so the agent works on the file structure itself, with the plugin inside the editor as the bridge.
The maintenance signal is mixed. The standalone penpot/penpot-mcp repository carries the banner “This repository was archived by the owner on Oct 7, 2026. It is now read-only,” with its last develop-branch commit dated Mar 19, 2026 (penpot-mcp GitHub). Its README, however, says the repository “has been archived on 2026-02-03” and that its contents were “fully integrated into the main Penpot repository” at the mcp directory of penpot/penpot. The two archive dates conflict, and the help site still documents setup through npx -y add-mcp. Check the main repository before building on either.
Where agents still fail on a spatial canvas
Neither Figma’s docs nor this review establish how accurately get_metadata or get_design_context represent auto-layout, constraints, or z-order. That perception beyond the documented surface is unverified, per Figma MCP tools and prompts. The failure modes below are documented ones, not speculation.
- Tool misselection. The agent picks the tool, “but not always” the right one, and the documented fix is rephrasing the prompt.
- Output cap. Each tool call can return up to 20 KB. This review did not measure how often real selections hit that ceiling.
- Pixels without semantics.
get_screenshotpreserves appearance but offers nothing to compute on. - Names without intent.
get_metadatayields IDs, positions, and sizes, stripped of styling. - Beta-quality writes. Output “may need manual review and cleanup.”
- Asset blockers. Locally installed fonts are unavailable to
use_figma; new images needupload_assetsorgenerate_image. - Maintenance ambiguity. The standalone Penpot MCP repository is archived, and its two archive dates conflict.
- Moving pricing. The write feature is beta-free now and documented as usage-based later.
None of these are failures of the canvas. They sit at the seam where a tool converts the canvas into an agent-readable payload, and every downstream computation inherits that conversion’s losses.
FAQ
What does an agent actually receive from a Figma file?
An agent never receives the file itself. You right-click a frame, choose “Copy link to selection,” and your MCP client extracts the node ID without opening the link. It then calls a tool: generated code with React and Tailwind by default, a lightweight XML outline of layer IDs and positions, variable definitions, or a screenshot (Figma MCP docs).
Can an agent write directly to the canvas?
Yes, through use_figma, which runs code via the Figma Plugin API to create and update frames, components, variants, variables, and auto layout. It requires the remote server and edit access, is free during beta but will become a usage-based paid feature, and its output “is beta quality and may need manual review and cleanup” (Figma write-to-canvas docs).
Is Penpot’s MCP server still maintained?
The standalone repository is archived and read-only. Its README says the code moved into the main Penpot repository, and the help site still documents the setup. The archive dates conflict (Feb 3 in the README, Oct 7 in the banner), so confirm the current code in the main repository before building (penpot-mcp GitHub, Penpot MCP help).
The Bottom Line
Perception on a design canvas is a set of partial views, and Figma’s own docs frame the server as giving agents “the design context they need to generate code” (Figma MCP docs), which is context, not the canvas. Every read tool trades completeness for a different kind of signal.
For builders, the consequence is to treat the tool surface as the perception system, not an implementation detail. Choose the slice deliberately: code for generation, metadata for targeting large files, variables for token work, screenshots only where appearance is the question. Design prompts and retries around documented behavior such as tool misselection. Any claim about what your agent “understands” from a canvas should trace to the endpoint that produced the payload. Then check the docs before committing an architecture, because the beta limits, the 20 KB cap, image and font handling, and write-to-canvas pricing are 2026 facts that may change.
How This Guide Was Built
This guide was compiled on October 17, 2026 from Figma’s and Penpot’s own documentation, including the Figma MCP docs and Penpot MCP help. This review is based on official documentation and vendor pages — we did not run these tools hands-on. No screenshots, benchmarks, or first-person tests were produced for it.
The dated limits, as of writing: Figma’s MCP pages are 2026 documents and write-to-canvas is beta, so the 20 KB per-call output cap, image and font handling, and pricing may change. What the documentation does not establish, including how accurately get_metadata or get_design_context represent auto-layout, constraints, or z-order, and which Penpot repository is authoritative, is labeled unverified above rather than stated as fact.