> ## Documentation Index > Fetch the complete documentation index at: https://docs.prisme.ai/llms.txt > Use this file to discover all available pages before exploring further. # Figma > Let Agent Factory agents read Figma files, comments, components, styles and library data through MCP, with per-user OAuth resolved server-side Figma The Figma connector exposes the [Figma](https://www.figma.com) design platform REST API to **Agent Factory** agents (through MCP) and to Builder automations (through the `Figma.op:` App instructions) — covering files, nodes, rendered images, comments, projects, components, styles, webhooks, variables, dev resources and library analytics. The 46 Figma operations are grouped into **13 entity tools**, each driven by an `action` argument. The MCP server runs in the **tenant app-instance context**: it resolves the installing workspace's own credentials and authorizes the calling agent against that workspace's allowlist. Authentication is per-user and supports several modes: * **Per-user OAuth2 — central client** (`oauthCentral`, recommended) — one Figma OAuth application is registered once by the platform maintainer; every end user signs in with their own Figma account. Nothing to register per workspace: each one just installs the app and clicks *Connect*. * **Per-user OAuth2 — tenant client** (`oauth`) — paste your own Figma OAuth client ID/secret in the connector config app. Each user signs in with their own account against your client (authorization-code + PKCE flow). * **Direct access token** (`accessToken`) — a caller-managed Figma token (e.g. a Personal Access Token), used as-is with no exchange. Files, nodes, rendered images, version history, components and styles Comments, reactions, dev resources, webhooks and library analytics Per-user OAuth (central or tenant client) resolved server-side, or a direct access token ## Who is this for? This connector is used by three different roles. Jump to the section that matches yours — each one is self-contained. You build agents in **Agent Factory** and want them to use Figma. → *Agent builder* tab. You run the platform and set up the shared Figma OAuth client once for everyone. → *Platform admin setup* accordion below. You write Builder automations (DSUL) that call Figma operations directly. → *Workspace builder* tab. ## Prerequisites * A **Figma** account. * For the **OAuth modes** — a Figma OAuth application created at **Figma > Developers > My apps** (`https://www.figma.com/developers/apps`); copy its Client ID and Client Secret. The platform maintainer registers one app for the central mode; a workspace can also register its own for the tenant mode. * For the **access-token mode** — a Personal Access Token created at **Figma > Settings > Security > Personal access tokens** (`https://www.figma.com/developers/api#access-tokens`) with the scopes the operations you call require. * The default OAuth scopes requested are: ```text theme={null} current_user:read file_content:read file_metadata:read file_versions:read file_comments:read projects:read ``` Add `file_variables:read` / `file_variables:write` (variables), `library_analytics:read` (library analytics) or `org:activity_log_read` (activity logs, Enterprise) when your agents need those endpoints. * Base URL: `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. **Goal:** two one-time tasks — (1) configure the shared **central OAuth client** so every workspace lets its users sign in with their own Figma account, and (2) optionally expose Figma as a reusable **capability** in AI Governance so agent builders can pick it without pasting endpoint URLs. Throughout, `` is your environment's API URL (`https://api.studio.prisme.ai/v2` on production). ## 1. Configure the connector Open `https://www.figma.com/developers/apps` and create a new app. Set the single authorized redirect URI (callback URL) to the **core workspace** callback: ```text theme={null} /workspaces/slug:figma/webhooks/oauthCallback ``` (e.g. `https://api.studio.prisme.ai/v2/workspaces/slug:figma/webhooks/oauthCallback` on production). Add the scopes listed in *Prerequisites*. Save and copy the **Client ID** and **Client Secret** (the secret is shown only once). Open the central `figma` workspace and launch its **Configuration app** — `/apps/figma` (e.g. `https://studio.prisme.ai/apps/figma`). Loaded from the core workspace, the app shows the **maintainer view** (org owner / editor / admin only); paste the **Client ID** and **Client Secret** there and Save — the app stores them in the core workspace's secrets for you. Do not edit Studio's raw Secrets by hand. These credentials stay in the `figma` workspace and are never exposed to tenants or end users; token exchange is proxied through the core `centralTokenExchange` webhook so the client secret never leaves the core workspace. Each consuming workspace selects auth mode **`oauthCentral`** in the connector configuration app (no client id/secret to enter on their side). Their users then just click **Connect**. From that same maintainer view, the **Add to catalog** button publishes Figma to the org-wide **Capabilities catalog** in one click (org owner / admin only; it stays disabled until the central client is saved). Once published, every agent builder in the org can enable Figma from the catalog without pasting an endpoint — see *Option A* in the *Agent builder* tab. ## 2. Declare the capability in AI Governance As an alternative to (or in addition to) the catalog button, you can declare Figma as a named **capability** in AI Governance. Agent builders then enable that capability on their agents instead of pasting a raw MCP endpoint. Create (or edit) the **Figma** capability. Set the capability's MCP server URL to the connector's **MCP Endpoint**, and set its **Scope** to: ```text theme={null} context_id,agent_id,user_id ``` The `agent_id` in the scope is what lets the connector identify and authorize the calling agent. Once created, the capability appears in the capability picker for agent builders in your organization, who enable it on their agents. Access to the catalog follows your organization's existing roles; there is no per-capability role grant. From an agent that has the capability, in a workspace configured for `oauthCentral`, trigger any tool (e.g. `users` with `action: "getMe"`). The user is prompted to connect once (Figma sign-in); subsequent calls reuse the stored token transparently and refresh it automatically. Declaring the capability makes the connector **available**; it does not by itself authorize a specific agent. This connector follows the **tenant-context model** — which agents may actually call it is gated per-workspace by the **authorized-agents allowlist** in the configuration app (see the *Workspace builder* tab). There is also **no OAuth auth-config JSON** to attach in Governance: connect / status / disconnect are handled by the connector's own webhooks, wired automatically. *** ## Agent builder **Goal:** let an agent you build in Agent Factory use Figma through MCP tools. Before an agent can call the connector, a *Workspace builder* must have installed and configured the Figma app in a workspace (see the *Workspace builder* tab), and — for the central OAuth mode — a *Platform admin* must have provisioned the shared OAuth client (see the *Platform admin setup* accordion above). This connector runs in the **tenant app-instance context**: your agent is authorized two ways at once — it is identified by the `agent_id` that Agent Factory injects through the capability *Scope*, and that agent must appear in the connector's **authorized-agents allowlist** (managed in the configuration app). The Figma access token itself is resolved server-side from the configured auth mode. There are two ways to wire it up. Pick based on how much isolation you need. ## Option A — Enable the shared capability from the catalog The fastest path: a *Platform admin* has already published a **Figma** capability to the Capabilities catalog (see the *Platform admin setup* accordion above — the **Add to catalog** button, or §2), so you just pick it from the catalog. Open the agent you want to extend and go to its capabilities / tools. Browse the capability catalog, select **Figma**, and enable it. The MCP endpoint URL and the *Scope* (`context_id,agent_id,user_id`) are already wired by the admin — nothing to paste, and the shared instance accepts every agent, so there is no allowlist step on your side. On the first tool call, an unconnected user is prompted to sign in — Agent Factory surfaces a `connect_url` to Figma's authorization page. After sign-in the per-user token is stored and reused on subsequent calls. Convenient, but your agent runs against a **shared, platform-managed instance**: its Figma credentials are owned by someone else and the instance accepts every agent that is granted the capability. Prefer Option B for anything beyond quick experiments. ## Option B — Run it from your own workspace (recommended) For production agents, install the connector in **your own workspace** and point the agent at *that* workspace's MCP endpoint. **Prefer this mode for security.** Because the MCP runs in *your* app-instance context, the Figma credentials, the per-user OAuth tokens and the authorized-agents allowlist are all **scoped to your workspace** — not shared platform-wide. You decide exactly which agents may call it and which Figma account / auth mode backs them, and a misconfiguration elsewhere can never expose your data. The shared catalog capability (Option A) is a broad surface many agents can reach; your own workspace is an isolated, least-privilege boundary. Follow the *Workspace builder* tab: install **Figma** in your workspace, open its **Configuration app**, choose the auth mode and connect a Figma account. In that workspace's config app, open **Authorized agents** and tick your agent (the **Install capability** button does this for you), or enable **Allow all agents**. In your agent, add a capability pointing at **your workspace's MCP Endpoint** URL, and set its **Scope** to: ```text theme={null} context_id,agent_id,user_id ``` The `agent_id` is what lets the connector identify and authorize your agent — without it, every call is rejected with an explicit "agent could not be identified" message. This *Scope* is separate from the Figma OAuth scopes. On the first tool call, the user is prompted to sign in (or uses **Connect** in the config app). The per-user token is stored and reused; refresh is automatic. ## Brief the agent in its system prompt Whichever option you pick, wiring the capability is not enough — the agent must know the connector exists and when to reach for it. Add a short paragraph to the agent's system prompt. Copy-pasteable starter: ```text theme={null} 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 tools 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 AI Knowledge agents** (no native MCP picker): add the connector under **Advanced > Tools > MCP** and paste the **MCP Endpoint** URL. The agent still has to be allowlisted in the config app and its identity propagated so the connector can read its `agent_id`. **Read-only by design.** Figma tools are read-only: the connector requests only `*:read` scopes (`current_user:read file_content:read file_metadata:read file_versions:read file_comments:read projects:read`) and exposes no write operation. Write-capable scopes (e.g. `file_variables:write`) are never obtained unless you explicitly add them to the **Scopes** field in the configuration app. No action is needed to keep this connector least-privilege. ## 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. | ## 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 ## Tool Details ### files Read document data for a file. The `action` selects what to return. ```json theme={null} { "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//...`) | | `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. ```json theme={null} { "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. ```json theme={null} { "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. ```json theme={null} { "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. ```json theme={null} { "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 | ## Workspace builder **Goal:** install the connector in a workspace, configure authentication and the agent allowlist, and call Figma operations from your automations. ## Installation 1. Go to **Apps** in your workspace 2. Search for **Figma** and install it 3. Open the **Configuration app** (the link auto-populated on install) to choose the auth mode, provide credentials, connect a Figma account, and allow the agents that may call the connector ## Configuration | Field | Description | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Configuration app** | Auto-populated on install — open this link to configure authentication (mode + credentials), connect a Figma account (OAuth modes), and manage the authorized-agents allowlist. | The configuration app drives everything; the app instance itself has no per-field credential form. From it you pick one of: | Auth mode | What you provide | Best for | | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | | `oauthCentral` | Nothing — just click **Connect** | Workspaces on a platform where the maintainer set up the central Figma client | | `oauth` | Your own Figma **Client ID + Secret** (redirect URI shown in the config app: `/workspaces/slug:/webhooks/.oauthCallback`) | You manage your own Figma OAuth app | | `accessToken` | A pre-minted Figma **access token** / Personal Access Token | Short-lived or caller-managed tokens | Credentials are stored in the workspace's Secrets (`figmaAuth`) and resolved server-side. The agent allowlist (**Authorized agents**, secret `figmaAuthorizedAgents`) gates which Agent Factory agents may call the MCP endpoint — see the *Agent builder* tab. Builder automations calling `Figma.op:` instructions resolve the same workspace credentials. ## Available Instructions Every instruction resolves credentials from the workspace configuration. The MCP server exposes the same operations behind the 13 entity tools (see the *Agent builder* tab). ### Files | Instruction | Description | Returns | | ----------------- | ------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | | `getFile` | Get the document JSON for a file by `file_key` (nodes, layers, styles); narrow with `ids`, `depth`, `geometry`, `version` | `{ document, components, styles, name, lastModified, version }` | | `getFileNodes` | Get JSON for specific nodes of a file by `file_key` + `ids` | `{ nodes: { : { document, components } } }` | | `getFileMeta` | Get metadata for a file by `file_key` (name, role, last touched, editor type) | `{ file: { name, role, last_touched_at, editorType } }` | | `getFileVersions` | List the version history of a file by `file_key`; paginate with `page_size`, `before`, `after` | `{ versions: [{ id, created_at, label, user }], pagination }` | ### Images | Instruction | Description | Returns | | --------------- | ---------------------------------------------------------------------------------- | ---------------------------------- | | `getImages` | Render nodes of a file by `file_key` + `ids` as `png`/`jpg`/`svg`/`pdf` at `scale` | `{ images: { : }, err }` | | `getImageFills` | Get download links for all image fills present in a file by `file_key` | `{ images: { : } }` | ### Comments | Instruction | Description | Returns | | ----------------------- | ---------------------------------------------------------------------------------------------- | --------------------------------------------------- | | `getComments` | List all comments on a file by `file_key`; `as_md` returns Markdown text | `{ comments: [{ id, message, user, created_at }] }` | | `postComment` | Post a comment (or reply via `comment_id`) on `file_key` with `message`; `client_meta` pins it | `{ id, message, user, created_at }` | | `deleteComment` | Delete a comment from `file_key` by `comment_id` | Empty (HTTP 200) | | `getCommentReactions` | List reactions on a comment by `file_key` + `comment_id`; paginate with `cursor` | `{ reactions: [{ emoji, user }], pagination }` | | `postCommentReaction` | Add a reaction `emoji` to a comment by `file_key` + `comment_id` | Empty (HTTP 200) | | `deleteCommentReaction` | Remove a reaction `emoji` from a comment by `file_key` + `comment_id` | Empty (HTTP 200) | ### Projects | Instruction | Description | Returns | | ----------------- | --------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | | `getTeamProjects` | List all projects within a team by `team_id` | `{ name, projects: [{ id, name }] }` | | `getProjectFiles` | List all files within a project by `project_id`; `branch_data` includes branch metadata | `{ name, files: [{ key, name, last_modified, thumbnail_url }] }` | ### Components | Instruction | Description | Returns | | ---------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | | `getTeamComponents` | List published components in a team library by `team_id`; paginate with `page_size`, `after`, `before` | `{ components: [{ key, name, description }], cursor }` | | `getFileComponents` | List published components within a file by `file_key` | `{ components: [{ key, name, node_id }] }` | | `getComponent` | Get metadata for a published component by `key` | `{ component: { key, name, description } }` | | `getTeamComponentSets` | List published component sets in a team library by `team_id`; paginate with `page_size`, `after`, `before` | `{ component_sets: [{ key, name }], cursor }` | | `getFileComponentSets` | List published component sets within a file by `file_key` | `{ component_sets: [{ key, name }] }` | | `getComponentSet` | Get metadata for a published component set by `key` | `{ component_set: { key, name } }` | ### Styles | Instruction | Description | Returns | | --------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------- | | `getTeamStyles` | List published styles in a team library by `team_id`; paginate with `page_size`, `after`, `before` | `{ styles: [{ key, name, style_type }], cursor }` | | `getFileStyles` | List published styles within a file by `file_key` | `{ styles: [{ key, name, style_type }] }` | | `getStyle` | Get metadata for a published style by `key` | `{ style: { key, name, style_type } }` | ### Users | Instruction | Description | Returns | | ----------- | ------------------------------------------ | -------------------------------- | | `getMe` | Get the authenticated Figma user's profile | `{ id, email, handle, img_url }` | ### Webhooks | Instruction | Description | Returns | | -------------------- | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | | `getWebhooks` | List webhooks filtered by `context` / `context_id` / `plan_api_id`; paginate with `cursor` | `{ webhooks: [{ id, event_type, endpoint, status }] }` | | `postWebhook` | Create a webhook for `event_type` posting to `endpoint` with `passcode`; scope via `team_id` / `context` / `context_id` | `{ id, event_type, endpoint, status }` | | `getWebhook` | Get a webhook by `webhook_id` | `{ id, event_type, endpoint, status }` | | `putWebhook` | Update a webhook by `webhook_id` (`event_type`, `endpoint`, `passcode`, `status`, `description`) | `{ id, event_type, endpoint, status }` | | `deleteWebhook` | Delete a webhook by `webhook_id` | Empty (HTTP 200) | | `getTeamWebhooks` | List webhooks for a team by `team_id` | `{ webhooks: [{ id, event_type, endpoint }] }` | | `getWebhookRequests` | List recent delivery attempts for a webhook by `webhook_id` | `{ requests: [{ request_info, response_info }] }` | ### Variables | Instruction | Description | Returns | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | | `getLocalVariables` | Get local variables of a file by `file_key` (Enterprise) | `{ meta: { variables, variableCollections } }` | | `getPublishedVariables` | Get published variables of a file by `file_key` (Enterprise) | `{ meta: { variables, variableCollections } }` | | `postVariables` | Create / update / delete variables in `file_key` via `variableCollections`, `variableModes`, `variables`, `variableModeValues` (Enterprise) | `{ meta: { tempIdToRealId } }` | ### Dev Resources | Instruction | Description | Returns | | ------------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------- | | `getDevResources` | List dev resources of a file by `file_key`; filter with `node_ids` | `{ dev_resources: [{ id, name, url, node_id }] }` | | `postDevResources` | Create dev resources across files; `dev_resources` = `[{ name, url, file_key, node_id }]` | `{ links_created, errors }` | | `putDevResources` | Update existing dev resources; `dev_resources` = `[{ id, name, url }]` | `{ links_updated, errors }` | | `deleteDevResource` | Delete a dev resource from `file_key` by `dev_resource_id` | Empty (HTTP 204) | ### Library Analytics | Instruction | Description | Returns | | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | | `getLibraryAnalyticsComponentActions` | Component action data for a library file by `file_key` + `group_by`; date range `start_date` / `end_date`, paginate with `cursor` | `{ rows: [...], next_page, cursor }` | | `getLibraryAnalyticsComponentUsages` | Component usage data for a library file by `file_key` + `group_by`; paginate with `cursor` | `{ rows: [...], next_page, cursor }` | | `getLibraryAnalyticsStyleActions` | Style action data for a library file by `file_key` + `group_by`; date range `start_date` / `end_date` | `{ rows: [...], next_page, cursor }` | | `getLibraryAnalyticsStyleUsages` | Style usage data for a library file by `file_key` + `group_by` | `{ rows: [...], next_page, cursor }` | | `getLibraryAnalyticsVariableActions` | Variable action data for a library file by `file_key` + `group_by`; date range `start_date` / `end_date` | `{ rows: [...], next_page, cursor }` | | `getLibraryAnalyticsVariableUsages` | Variable usage data for a library file by `file_key` + `group_by` | `{ rows: [...], next_page, cursor }` | ### Activity Logs | Instruction | Description | Returns | | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | | `getActivityLogs` | Query organization activity logs (Enterprise / org-scoped OAuth token); filter by `events`, `start_time`, `end_time`, `limit`, `order` | `{ activity_logs: [...], next_page, cursor }` | ### Embed | Instruction | Description | Returns | | ----------- | ------------------------------------------------------------------------------------------ | -------------------------------------- | | `getOEmbed` | Get oEmbed data for a public Figma file/prototype `url`; size with `maxwidth`, `maxheight` | `{ type, title, html, thumbnail_url }` | `Returns` shows the shape of the operation output (the underlying Figma API resource). ## DSUL Examples ### Read a file's metadata ```yaml theme={null} - Figma.getFileMeta: file_key: '{{fileKey}}' output: meta ``` ### Post a comment on a file ```yaml theme={null} - Figma.postComment: file_key: '{{fileKey}}' message: Please review the updated hero section. output: comment ``` ### Render PNGs of selected nodes ```yaml theme={null} - 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 ```yaml theme={null} - Figma.postWebhook: event_type: FILE_UPDATE context: file context_id: '{{fileKey}}' endpoint: 'https://example.com/figma-hook' passcode: '{{webhookSecret}}' output: webhook ``` *** ## Error Handling | HTTP Status | Error | Solution | | ----------- | ------------ | ----------------------------------------------------------------------------------------------------------- | | 400 | Bad request | Check argument shapes (node ids, dates, enum values) | | 401 | Unauthorized | Sign in again (OAuth modes), or verify the access token | | 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 **"This agent is not authorized to use this connector"** — The calling agent is not in the allowlist. Open the configuration app → **Authorized agents** → tick this agent (id is shown in the error) or enable **Allow all agents**, and Save. The **Install capability** button does this for you. **"The calling agent could not be identified"** — The MCP capability *Scope* does not declare `agent_id`, so Agent Factory never injects the agent identity. Set the Scope to `context_id,agent_id,user_id` on the capability (this is separate from the Figma OAuth scopes), then allow the agent in the config app. **"Figma is not connected for this user"** — No per-user OAuth token is stored for the caller. Open the configuration app (OAuth mode) and click **Connect**, or use the agent's connect flow. **"Figma token refresh failed … must reconnect"** — The stored refresh token was rejected by Figma (revoked / expired). The connection is dropped automatically; the user must reconnect from the config app. **"Figma OAuth is not configured"** — Neither a tenant OAuth client nor the central platform client is available. Set the OAuth client ID/secret in the config app (tenant mode), or ask the platform maintainer to provision the central OAuth client from the core workspace's config app. **Activity logs require OAuth** — `getActivityLogs` (the `activityLogs` tool) only accepts an OAuth bearer token with `org:activity_log_read`; a plain access token without that scope is rejected. This endpoint is Enterprise-only. **No token revocation** — Figma has no token-revocation endpoint, so disconnecting deletes the stored tokens on Prisme.ai's side rather than revoking them at Figma. ## External Resources Official Figma REST API reference Learn how Agent Factory agents consume MCP tools in Prisme.ai.