Figma

Read Figma files, comments, components, styles and library data from Prisme.ai workflows and AI agents

The Figma app provides access to the Figma design platform via its REST API. It can be used either as a Builder app (automations call Figma instructions directly) or as a remote MCP server consumed by an AI agent — covering files, nodes, rendered images, comments, projects, components, styles, webhooks, variables, dev resources and library analytics. The MCP layer groups the 46 operations into 13 entity tools, each driven by an action argument. Supports both a static Personal Access Token and OAuth2 authorization-code per-user delegation.

Design Files

Files, nodes, rendered images, version history, components and styles

Collaboration

Comments, reactions, dev resources, webhooks and library analytics

Flexible Auth

Static Personal Access Token shared across the tenant, or OAuth2 per-user delegation (each user signs in with their own Figma account)

Prerequisites

• A Figma account
• Either a Personal Access Token (Figma Settings > Security > Personal access tokens) with the read/write scopes you need, or an OAuth2 app registered at Figma > Developers > My apps (https://www.figma.com/developers/apps)
• Some endpoints require specific scopes: variables need file_variables:read / file_variables:write, library analytics need library_analytics:read, and activity logs need an OAuth token with org:activity_log_read (Enterprise only)
• Base URL (default: https://api.figma.com — paths already include /v1 or /v2)

Figma variables, dev resources and library analytics are gated by plan tier (Enterprise / Organization). The connector exposes them, but the Figma API returns 403 if your account or token is not entitled.

---

Usage as App

Installation

1. Go to Apps in your workspace
2. Search for Figma and install it
3. Open the app instance configuration and fill in the required fields

Configuration

Field	Description
Figma API Base URL	Base URL of the Figma API (default https://api.figma.com).
Personal Access Token	Figma Personal Access Token, stored as a workspace secret. Optional if OAuth2 is configured. Sent as the X-Figma-Token header.
OAuth2 Client ID	Figma OAuth app Client ID. Create an app at https://www.figma.com/developers/apps. Stored as a workspace secret.
OAuth2 Client Secret	Figma OAuth app Client Secret, stored as a workspace secret.
OAuth Callback URL	Auto-populated on install — paste this value into the OAuth app’s redirect URL field at Figma.
OAuth Authorize URL	Default https://www.figma.com/oauth.
OAuth Token URL	Default https://api.figma.com/v1/oauth/token (the refresh endpoint /v1/oauth/refresh is derived from it).
OAuth Scopes	Space-separated Figma OAuth scopes. A broad read/write default is provided.
Refresh Token TTL (seconds)	How long to retain the stored refresh token. Default 7776000 (90 days).
MCP Endpoint	Auto-populated on install — URL of the MCP endpoint for this instance.
MCP API Key	Auto-populated on install — signed key used in the mcp-api-key header. Do not modify.

MCP Endpoint and MCP API Key are generated automatically by the onInstall flow and are only needed to expose this instance as an MCP server (see the next tab).

OAuth2 per-user setup (optional)

To let each user act with their own Figma account instead of a shared token:

1. Create an OAuth app at Figma > Developers > My apps.
2. After installing the Prisme.ai app, copy the OAuth Callback URL from the configuration and paste it into the Figma OAuth app’s redirect URL field.
3. Paste the Figma app’s Client ID and Client Secret into OAuth2 Client ID / OAuth2 Client Secret.
4. Users authorize on first use via the connect tool (MCP) — a per-user refresh token is stored and reused.

Available Instructions

Every instruction resolves credentials from the workspace configuration.

Files

Instruction	Arguments
getFile	file_key*, version, ids, depth, geometry, plugin_data, branch_data
getFileNodes	file_key, ids, version, depth, geometry, plugin_data
getFileMeta	file_key*
getFileVersions	file_key*, page_size, before, after

Images

Instruction	Arguments
getImages	file_key, ids, version, scale, format, svg_outline_text, svg_include_id, svg_include_node_id, svg_simplify_stroke, contents_only, use_absolute_bounds
getImageFills	file_key*

Comments

Instruction	Arguments
getComments	file_key*, as_md
postComment	file_key, message, comment_id, client_meta
deleteComment	file_key, comment_id
getCommentReactions	file_key, comment_id, cursor
postCommentReaction	file_key, comment_id, emoji*
deleteCommentReaction	file_key, comment_id, emoji*

Projects

Instruction	Arguments
getTeamProjects	team_id*
getProjectFiles	project_id*, branch_data

Components

Instruction	Arguments
getTeamComponents	team_id*, page_size, after, before
getFileComponents	file_key*
getComponent	key*
getTeamComponentSets	team_id*, page_size, after, before
getFileComponentSets	file_key*
getComponentSet	key*

Styles

Instruction	Arguments
getTeamStyles	team_id*, page_size, after, before
getFileStyles	file_key*
getStyle	key*

Users

Instruction	Arguments
getMe	–

Webhooks

Instruction	Arguments
getWebhooks	context, context_id, plan_api_id, cursor
postWebhook	event_type, endpoint, passcode*, team_id, status, description, plan_api_id, context, context_id
getWebhook	webhook_id*
putWebhook	webhook_id*, event_type, endpoint, passcode, status, description
deleteWebhook	webhook_id*
getTeamWebhooks	team_id*
getWebhookRequests	webhook_id*

Variables

Instruction	Arguments
getLocalVariables	file_key*
getPublishedVariables	file_key*
postVariables	file_key*, variableCollections, variableModes, variables, variableModeValues

Dev Resources

Instruction	Arguments
getDevResources	file_key*, node_ids
postDevResources	dev_resources*
putDevResources	dev_resources*
deleteDevResource	file_key, dev_resource_id

Library Analytics

Instruction	Arguments
getLibraryAnalyticsComponentActions	file_key, group_by, cursor, start_date, end_date
getLibraryAnalyticsComponentUsages	file_key, group_by, cursor
getLibraryAnalyticsStyleActions	file_key, group_by, cursor, start_date, end_date
getLibraryAnalyticsStyleUsages	file_key, group_by, cursor
getLibraryAnalyticsVariableActions	file_key, group_by, cursor, start_date, end_date
getLibraryAnalyticsVariableUsages	file_key, group_by, cursor

Activity Logs

Instruction	Arguments
getActivityLogs	events, start_time, end_time, limit, order

Embed

Instruction	Arguments
getOEmbed	url*, maxwidth, maxheight

Arguments flagged with * are required.

DSUL Examples

Read a file’s metadata

- Figma.getFileMeta:
    file_key: '{{fileKey}}'
    output: meta

Post a comment on a file

- Figma.postComment:
    file_key: '{{fileKey}}'
    message: Please review the updated hero section.
    output: comment

Render PNGs of selected nodes

- Figma.getFile:
    file_key: '{{fileKey}}'
    depth: 1
    output: file
- Figma.getImages:
    file_key: '{{fileKey}}'
    ids: '1:23,1:45'
    format: png
    scale: 2
    output: renders

Subscribe to file updates with a webhook

- Figma.postWebhook:
    event_type: FILE_UPDATE
    context: file
    context_id: '{{fileKey}}'
    endpoint: 'https://example.com/figma-hook'
    passcode: '{{webhookSecret}}'
    output: webhook

Usage as MCP

The Figma app ships with a built-in MCP server. Each app instance gets its own signed mcp-api-key that encodes the workspace ID and a credentials lookup URL — the Figma credentials themselves are never passed through headers and are resolved server-side from the app configuration.

The MCP layer is entity-grouped: instead of one tool per operation, the 46 Figma operations are exposed as 13 entity tools. Each tool takes an action argument selecting the operation to run (for example, the files tool with action: "get" runs getFile).

Plug into an Agent Creator capability

Agents consume MCP servers directly through Agent Creator capabilities. This is the preferred way to expose Figma to an agent.

1. Create or open a workspace

   From the Prisme.ai console, create a new workspace (or open the one that will host the connector).

2. Install the Figma app

   Open the workspace Imports panel, search for Figma and install it.

3. Configure the credentials

   Open the freshly installed app instance settings and fill in the required fields (see the Usage as App tab for the field-by-field reference).

4. Copy the MCP endpoint and API key

   Still on the app instance configuration page, copy the values of MCP Endpoint and MCP API Key — both are generated automatically on install.

5. Open Agent Creator

   Switch to Agent Creator and open the agent you want to extend.

6. Add a capability

   Add a new capability to the agent:

   • If a dedicated Figma capability exists — select it and paste the MCP API Key into the mcp-api-key field. The server URL is already wired.

   • Otherwise — select the generic custom_mcp capability, paste the MCP Endpoint into the Server URL field, then open the Headers field and add an mcp-api-key entry whose value is the MCP API Key copied earlier:

     {
       "mcp-api-key": "your-mcp-api-key"
     }
     
7. Save

   The agent now has access to every Figma tool exposed by the MCP server.

8. Brief the agent in its system prompt

   Wiring the capability is not enough — the agent also needs to know the MCP exists and when to reach for it. Add a short paragraph to the agent’s system prompt. Copy-pasteable starter:

   You have access to the Figma MCP server. Use it whenever the user asks about Figma content — files, nodes, rendered images, comments, projects, components, styles, webhooks, variables or library analytics. Examples: "Summarize the comments on this Figma file", "Render the hero frame as a PNG", "List the published components in our design system". Each tool is an entity that takes an `action` argument. Prefer calling MCP tools directly over guessing, and confirm with the user before any destructive action (delete a comment, delete a webhook, modify variables).
   

   Refine the trigger keywords (file keys, team names, component conventions) so the agent reliably picks up the right intent in your context.

Legacy MCP Install (Advanced > Tools)

Use this flow to plug the Figma MCP into an AI Knowledge agent that does not yet support the native MCP picker.

1. Install the Figma app

   Install and configure the app in the same workspace as your agent (see the Usage as App tab). Once configured, mcpEndpoint and mcpApiKey are auto-populated.

2. Copy the MCP credentials

   Open the app instance config and copy the values of MCP Endpoint and MCP API Key.

3. Open your AI Knowledge project

   Navigate to Advanced > Tools.

4. Add an MCP tool

   Click Add and select the MCP tab.

5. Fill in the endpoint

   Paste the MCP Endpoint URL copied from the app instance.

6. Add the auth header

   In the Headers field, add the signed API key:

   {
     "mcp-api-key": "your-mcp-api-key"
   }
   
7. Save

   The agent can now list and call Figma tools through the MCP endpoint.

The signed mcp-api-key encodes the workspace ID and the getConfig webhook URL. The MCP server validates the signature using the central app secret and transparently fetches the Figma credentials and base URL from the installed app. Credentials are cached per tenant for 10 minutes.

Output Formats

Every tool accepts an outputFormat parameter that controls the MCP response shape:

• verbose (default) — human-readable text for LLM consumption
• structured — machine-readable JSON in structuredContent
• both — both text and structured content

Available Tools

Each tool is an entity. Pass the action argument to select the operation, plus the parameters that operation needs.

Tool	Actions	Description
files	get, getNodes, getMeta, getVersions	Figma files — read document JSON, nodes, metadata and version history.
images	render, getFills	Render images of Figma nodes and fetch image-fill download links.
comments	list, create, delete, listReactions, addReaction, deleteReaction	Comments and comment reactions on a Figma file.
projects	listByTeam, listFiles	Figma team projects and the files they contain.
components	listByTeam, listByFile, get, listSetsByTeam, listSetsByFile, getSet	Published components and component sets (file- or team-level).
styles	listByTeam, listByFile, get	Published styles (file- or team-level).
users	getMe	The authenticated Figma user.
webhooks	list, create, get, update, delete, listByTeam, getRequests	Figma webhooks v2 — subscribe to file and library events.
variables	getLocal, getPublished, modify	Figma variables (Enterprise) — local, published and bulk modify.
devResources	list, create, update, delete	Dev resources (Dev Mode links) attached to files.
analytics	componentActions, componentUsages, styleActions, styleUsages, variableActions, variableUsages	Library analytics — component, style and variable actions and usages.
activityLogs	list	Organization activity logs (Enterprise / org-scoped token).
embed	get	oEmbed metadata for a public Figma URL.

OAuth Session

Tool	Description
connect	Connect a Figma account via OAuth2 so the workspace can act on the user’s behalf. Returns a sign-in link. Only needed when the user explicitly wants to connect their own account.
disconnect	Disconnect the current Figma OAuth session and delete the stored tokens.

Tool Details

files

Read document data for a file. The action selects what to return.

{
  "name": "files",
  "arguments": {
    "action": "get",
    "file_key": "omLm4Pdg2a3BzTKU8EcDo7",
    "depth": 1
  }
}

Parameter	Required	Description
action	Yes	get, getNodes, getMeta or getVersions
file_key	Yes	File key from the Figma file URL (figma.com/design/<file_key>/...)
ids	For getNodes	Comma-separated node ids
depth	No	Tree traversal depth (limits the document JSON size)
version	No	Specific file version id (defaults to current)
geometry	No	Set to paths to export vector geometry

comments

List, create and delete comments and reactions on a file.

{
  "name": "comments",
  "arguments": {
    "action": "create",
    "file_key": "omLm4Pdg2a3BzTKU8EcDo7",
    "message": "Please review the updated hero section."
  }
}

Parameter	Required	Description
action	Yes	list, create, delete, listReactions, addReaction, deleteReaction
file_key	Yes	Target file key
message	For create	Comment text
comment_id	For delete / reactions / a reply	Target comment id
emoji	For addReaction / deleteReaction	Emoji shortcode, e.g. :eyes:
client_meta	No	Pin location for the comment ({x, y} vector or frame offset)

images

Render nodes as images, or fetch the download links of a file’s image fills.

{
  "name": "images",
  "arguments": {
    "action": "render",
    "file_key": "omLm4Pdg2a3BzTKU8EcDo7",
    "ids": "1:23,1:45",
    "format": "png",
    "scale": 2
  }
}

Parameter	Required	Description
action	Yes	render or getFills
file_key	Yes	Target file key
ids	For render	Comma-separated node ids to render
format	No	jpg, png, svg or pdf
scale	No	Render scale, 0.01–4

webhooks

Manage Figma v2 webhooks subscribing to file and library events.

{
  "name": "webhooks",
  "arguments": {
    "action": "create",
    "event_type": "FILE_UPDATE",
    "context": "file",
    "context_id": "omLm4Pdg2a3BzTKU8EcDo7",
    "endpoint": "https://example.com/figma-hook",
    "passcode": "a-shared-secret"
  }
}

Parameter	Required	Description
action	Yes	list, create, get, update, delete, listByTeam, getRequests
event_type	For create	e.g. FILE_UPDATE, FILE_COMMENT, LIBRARY_PUBLISH
endpoint	For create	HTTPS endpoint that receives webhook events
passcode	For create	Shared secret sent with each event
context / context_id	No	Scope the webhook to a team, project or file
webhook_id	For get / update / delete / getRequests	Target webhook id

components

Browse published components and component sets at file or team level.

{
  "name": "components",
  "arguments": {
    "action": "listByTeam",
    "team_id": "1303310645528056530"
  }
}

Parameter	Required	Description
action	Yes	listByTeam, listByFile, get, listSetsByTeam, listSetsByFile, getSet
team_id	For team-level actions	Figma team id
file_key	For file-level actions	Target file key
key	For get / getSet	Published component / component set key

---

Error Handling

HTTP Status	Error	Solution
400	Bad request	Check argument shapes (node ids, dates, enum values)
401	Unauthorized	Verify the Personal Access Token, or re-authorize OAuth
403	Forbidden	The token lacks the required scope or plan entitlement — Figma names the missing scope in the error message
404	Not Found	Verify the file_key, team_id, project_id or resource id
429	Rate Limited	Figma throttles per token; back off and retry
500	Server Error	Transient Figma issue; retry after a few seconds

Common Issues

“Not configured” — The app instance has no credentials. Add a Personal Access Token (or configure OAuth2) in the app configuration.

“Invalid API key” (MCP) — The mcp-api-key header does not match the central app secret. Reinstall the app instance to regenerate a signed key.

“Credentials lookup failed” — The MCP endpoint could not reach the getConfig webhook of the installed app. Verify that the app instance is still installed in the expected workspace.

“Invalid scope” — The Personal Access Token (or OAuth grant) was created without a scope an endpoint requires. Variables endpoints need file_variables:read / file_variables:write, library analytics need library_analytics:read. Regenerate the token with the missing scope enabled.

Activity logs require OAuth — getActivityLogs (the activityLogs tool) only accepts an OAuth bearer token with org:activity_log_read; a Personal Access Token is rejected. This endpoint is Enterprise-only.

PAT vs OAuth headers — A Personal Access Token is sent as the X-Figma-Token header; OAuth delegated tokens are sent as Authorization: Bearer. The connector selects the correct header automatically based on how the credential was supplied.

OAuth per-user delegation — Each Figma user must click the connect tool once (from the AI agent) to authorize; the connector stores a per-user refresh token. Use disconnect to clear it. Figma has no token-revocation endpoint, so disconnect deletes the stored tokens.

External Resources

Figma REST API

Official Figma REST API reference

Tool Agents

Plug MCP servers into AI Knowledge agents