# Understanding the whoami Tool and Authentication in Figma MCP

> Learn about the whoami tool and authentication in Figma MCP. Discover how this mandatory first step authenticates users and retrieves identity details for secure platform access.

- Repository: [Figma/mcp-server-guide](https://github.com/figma/mcp-server-guide)
- Tags: how-to-guide
- Published: 2026-03-30

---

**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`](https://github.com/figma/mcp-server-guide/blob/main/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`](https://github.com/figma/mcp-server-guide/blob/main/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`](https://github.com/figma/mcp-server-guide/blob/main/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`](https://github.com/figma/mcp-server-guide/blob/main/figma-power/POWER.md) | Lists `whoami` among all remote MCP tools in the "Power" table |
| [`README.md`](https://github.com/figma/mcp-server-guide/blob/main/README.md) | Provides the user-facing description under the "whoami (remote only)" section |
| [`skills/figma-create-new-file/SKILL.md`](https://github.com/figma/mcp-server-guide/blob/main/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:

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

```

The typical response structure:

```json
{
  "email": "alice@example.com",
  "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:

```javascript
// 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`](https://github.com/figma/mcp-server-guide/blob/main/skills/figma-create-new-file/SKILL.md), the canonical skill flow follows this structure:

```text
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`](https://github.com/figma/mcp-server-guide/blob/main/figma-power/POWER.md), user documentation in [`README.md`](https://github.com/figma/mcp-server-guide/blob/main/README.md), and workflow patterns in [`skills/figma-create-new-file/SKILL.md`](https://github.com/figma/mcp-server-guide/blob/main/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`](https://github.com/figma/mcp-server-guide/blob/main/README.md) and [`figma-power/POWER.md`](https://github.com/figma/mcp-server-guide/blob/main/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`](https://github.com/figma/mcp-server-guide/blob/main/figma-power/POWER.md) (technical tool definition), the [`README.md`](https://github.com/figma/mcp-server-guide/blob/main/README.md) under the "whoami (remote only)" section (user-facing description), and [`skills/figma-create-new-file/SKILL.md`](https://github.com/figma/mcp-server-guide/blob/main/skills/figma-create-new-file/SKILL.md) (implementation workflow showing how skills depend on `whoami` for authentication).