Understanding the whoami Tool and Authentication in Figma MCP

The whoami tool is a remote-only MCP endpoint that authenticates the current user and returns their identity details and available Figma plans, serving as the mandatory first step for any authenticated operation in the Figma MCP platform.

The figma/mcp-server-guide repository documents the Figma MCP (Machine-Code-Power) platform, where every authenticated request begins with a single tool. Understanding the whoami tool and authentication in Figma MCP is essential for developers building AI assistants that create files, read designs, or manage components on behalf of users.

What Is the whoami Tool?

The whoami tool is a remote-only MCP tool—meaning it does not execute locally but rather contacts Figma's backend servers to verify the authenticated session. When invoked, it returns a JSON payload containing the user's identity and organizational context required for downstream operations.

The response payload includes two critical fields:

• email: The user's primary email address associated with the Figma account.
• plans: An array of plan objects, each containing:
  • key: The unique identifier (e.g., team:123456) required by other tools
  • name: The human-readable team or organization name
  • seat: The user's role (e.g., admin, member)
  • tier: The subscription level (e.g., enterprise, pro)

Authentication Flow and Plan Resolution

The Remote Authentication Pattern

According to the source code in figma-power/POWER.md, whoami is defined as a remote tool that resolves the user's OAuth token against Figma's identity service. The README.md further clarifies that this tool is explicitly marked as "remote only," distinguishing it from local computation tools.

Extracting and Selecting Plan Keys

Many MCP tools, such as create_new_file, require a planKey parameter. The workflow documented in skills/figma-create-new-file/SKILL.md establishes a clear decision tree:

1. If the user provides a planKey: Use it directly.
2. If no planKey exists: Call whoami, inspect the plans array, and select the appropriate key.
   • For single-plan users, the assistant selects automatically.
   • For multi-plan users, the assistant should prompt the user to choose between teams or organizations.

Source Code References and Architecture

The tool definition spans three key files in the figma/mcp-server-guide repository:

File	Purpose
figma-power/POWER.md	Lists whoami among all remote MCP tools in the "Power" table
README.md	Provides the user-facing description under the "whoami (remote only)" section
skills/figma-create-new-file/SKILL.md	Demonstrates the canonical workflow that depends on whoami for plan resolution

Code Examples and Implementation

Direct JSON Request and Response

To invoke the tool directly, send an empty parameter request:

{
  "tool": "whoami",
  "parameters": {}
}

The typical response structure:

{
  "email": "[email protected]",
  "plans": [
    {
      "key": "team:123456",
      "name": "Acme Corp",
      "seat": "admin",
      "tier": "enterprise"
    },
    {
      "key": "team:789012",
      "name": "Side-Project",
      "seat": "member",
      "tier": "pro"
    }
  ]
}

Resolving planKey Before File Creation

This JavaScript example demonstrates the complete authentication and file creation flow:

// 1️⃣ Call whoami to authenticate
const whoamiResponse = await callMcpTool('whoami');

// 2️⃣ Pick a plan key based on available plans
let planKey;
if (whoamiResponse.plans.length === 1) {
  planKey = whoamiResponse.plans[0].key;  // Auto-select single plan
} else {
  // In production, ask the user which team to target
  planKey = whoamiResponse.plans[0].key;  // Default to first for demo
}

// 3️⃣ Create a new design file using the resolved planKey
const createFileResponse = await callMcpTool('create_new_file', {
  planKey,
  fileName: 'My New Design',
  editorType: 'design'
});

// 4️⃣ Use the newly created file
console.log('File URL:', createFileResponse.file_url);

Skill-Level Workflow Documentation

As documented in skills/figma-create-new-file/SKILL.md, the canonical skill flow follows this structure:

Step 1 – Resolve the planKey
  • If the user already supplied a planKey → use it.
  • Otherwise → call `whoami` and pick a key from the returned `plans`.

Step 2 – Call `create_new_file` with:
  {
    "planKey": "<chosen-key>",
    "fileName": "My New Design",
    "editorType": "design"
  }

Step 3 – Receive `file_key` and `file_url` for further MCP calls (e.g., `use_figma`).

Summary

• The whoami tool is the remote-only authentication endpoint for all Figma MCP operations.
• It returns the user's email and an array of plans containing key, name, seat, and tier properties.
• Plan resolution requires calling whoami when no planKey is provided, selecting automatically for single-plan users or prompting for multi-plan scenarios.
• Tool definitions reside in figma-power/POWER.md, user documentation in README.md, and workflow patterns in skills/figma-create-new-file/SKILL.md.

Frequently Asked Questions

What does the whoami tool return?

The tool returns a JSON object containing the authenticated user's email address and a plans array. Each plan object includes a key (used for subsequent tool calls), name (display name), seat (role), and tier (subscription level).

Is whoami a local or remote tool?

whoami is explicitly a remote-only tool. According to the repository's README.md and figma-power/POWER.md, it contacts Figma's backend servers to validate the OAuth token and retrieve current identity information, rather than executing locally within the MCP runtime.

How do I choose the right planKey?

If the user belongs to a single plan, automatically select plans[0].key. If multiple plans exist, the assistant should present the available options (using the name field for display) and ask the user which team or organization to target before proceeding with tools like create_new_file.

Where is whoami documented in the repository?

The tool is documented across three locations: the "Power" table in figma-power/POWER.md (technical tool definition), the README.md under the "whoami (remote only)" section (user-facing description), and skills/figma-create-new-file/SKILL.md (implementation workflow showing how skills depend on whoami for authentication).

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}