# Troubleshooting MCP Server Connection Issues: Complete Diagnostic Guide

> Resolve MCP server connection issues with this diagnostic guide. Troubleshoot config errors, outdated extensions, and blocked localhost assets for seamless Figma integration.

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

---

**Most Figma MCP server connection failures stem from three layers: incorrect server configuration in [`mcp.json`](https://github.com/figma/mcp-server-guide/blob/main/mcp.json), outdated client extensions missing required tools, or localhost asset endpoints being blocked by the client.**

When AI agents cannot retrieve design data from Figma, the breakdown typically occurs between the MCP client (VS Code, Cursor, or Claude Code) and the Figma MCP server hosted at `https://mcp.figma.com/mcp`. This guide walks through systematic troubleshooting using the official `figma/mcp-server-guide` repository, covering network diagnostics, tool validation, and asset endpoint resolution.

## The Three Layers of Connection Failures

Connection issues fall into distinct categories based on where the handshake fails. According to the source documentation in `figma/mcp-server-guide`, you should diagnose these layers sequentially.

### Network and Server Configuration

The most common failure point is an incorrect entry in the client's MCP server configuration. The server must be registered with the exact ID `figma` and URL `https://mcp.figma.com/mcp` as specified in the repository's **Connect to the Figma MCP server** section.

If the **MCP chat** shows no available tools when you type `#`, the client cannot reach the server. Verify your [`mcp.json`](https://github.com/figma/mcp-server-guide/blob/main/mcp.json) or `mcpServers` configuration against the canonical snippet in [[`README.md`](https://github.com/figma/mcp-server-guide/blob/main/README.md)](https://github.com/figma/mcp-server-guide/blob/main/README.md#example-mcpjson). Restart your editor after correcting the entry, as the UI may cache stale configuration data.

### MCP Tool Availability

When the server is reachable but specific tools like `get_design_context` or `get_metadata` are missing, the client extension is likely outdated. Run `#list_tools` in the chat to see the registered capabilities.

If the expected tools do not appear in the autocomplete list, update your MCP client extension to the latest version. For advanced features like Code Connect, ensure feature flags such as `pixie_mcp_enable_writing_code_connect_templates` are enabled as documented in the Skills section.

### Asset Endpoint and URL Handling

Successful design context calls may still fail to load images if the client blocks `localhost` URLs. When `#get_design_context` returns an `src` field pointing to `http://localhost:PORT/...` and the client reports a 404, you are encountering the **Assets not loading** issue documented in [[`skills/figma-implement-design/SKILL.md`](https://github.com/figma/mcp-server-guide/blob/main/skills/figma-implement-design/SKILL.md)](https://github.com/figma/mcp-server-guide/blob/main/skills/figma-implement-design/SKILL.md#issue-assets-not-loading).

Enable "Allow insecure localhost connections" in your MCP settings (VS Code), or expose the local server via a tunnel like `ngrok`. Do not rewrite the URL; use the provided endpoint as-is.

## Step-by-Step Diagnostic Workflow

Follow this sequence to isolate the root cause of connection failures.

1. **Confirm the server URL** — Open your editor's MCP settings and compare the configuration against the reference in [`README.md`](https://github.com/figma/mcp-server-guide/blob/main/README.md). Ensure the ID is `figma` and the URL is `https://mcp.figma.com/mcp`.

2. **Validate tool registration** — Type `#` in the chat window. If `get_design_context`, `get_metadata`, or `get_screenshot` are missing, reinstall the MCP plugin.

3. **Test a minimal call** — Execute a basic tool call to verify end-to-end connectivity:

   ```text
   #get_design_context fileKey="YOUR_FILE_KEY" nodeId="0:1"
   ```

   A successful response returns JSON with component data. Capture any error messages if this fails.

4. **Inspect asset endpoints** — Run `#get_metadata` on the same node and examine the `assets` fields. If URLs contain `localhost`, ensure your client can reach that endpoint directly.

5. **Check network diagnostics** — Ping `mcp.figma.com` from your terminal to verify outbound HTTPS is not blocked by corporate firewalls or proxy settings.

6. **Apply error recovery** — Follow the systematic workflow in [[`skills/figma-use/references/validation-and-recovery.md`](https://github.com/figma/mcp-server-guide/blob/main/skills/figma-use/references/validation-and-recovery.md)](https://github.com/figma/mcp-server-guide/blob/main/skills/figma-use/references/validation-and-recovery.md): stop execution, read the error message, call `get_metadata` or `get_screenshot` for additional context, fix the underlying issue, then retry the operation.

## Practical Code Examples for Testing Connectivity

Use these specific commands and code snippets to diagnose connection health.

### Verify Tool Registration

Test if the client recognizes the Figma server tools:

```text
#list_tools

```

**Expected output:**

```

Available MCP tools:
- get_design_context
- get_metadata
- get_screenshot
- get_code_connect_suggestions

```

If `get_design_context` is absent, the server configuration is incorrect or the plugin requires reinstallation.

### Test Design Context Retrieval

Verify the server can access Figma file data:

```text
#get_design_context fileKey="kL9xQn2VwM8pYrTb4ZcHjF" nodeId="42:15"

```

**Successful response excerpt:**

```json
{
  "componentName": "Button",
  "source": "src/components/Button.tsx",
  "label": "React",
  "properties": { }
}

```

### Diagnose Asset Loading Issues

Check if image URLs are accessible:

```text
#get_design_context fileKey="kL9xQn2VwM8pYrTb4ZcHjF" nodeId="42:15"

```

Look for `src` fields containing `http://localhost:3000/assets/...`. If the client cannot fetch these, adjust local server settings or use a tunnel rather than rewriting URLs.

### Implement Error Recovery

When building `use_figma` scripts, structure error handling to leverage the MCP runtime's automatic capture:

```javascript
// Pseudo-code for use_figma skill execution
try {
  const nodes = await figma.getNodeByIdAsync(nodeId);
  // ... your logic ...
  return { success: true, nodeIds: [nodes.id] };
} catch (e) {
  // Let the MCP runtime capture the error automatically
  throw new Error(`MCP call failed: ${e.message}`);
}

```

When this script throws, the MCP client returns an error object visible in the chat. Consult the **Validation and Recovery** guide for next steps.

## Summary

- **Configuration errors** are the most frequent cause; verify the server ID is `figma` and the URL is `https://mcp.figma.com/mcp` in [`mcp.json`](https://github.com/figma/mcp-server-guide/blob/main/mcp.json).
- **Missing tools** indicate an outdated client extension; update VS Code, Cursor, or Claude Code plugins and enable required feature flags.
- **Localhost asset failures** require allowing insecure connections or tunneling via `ngrok` without URL rewriting.
- Use `#list_tools` and `#get_design_context` as diagnostic probes to confirm connectivity layers.
- Follow the systematic recovery workflow in [`skills/figma-use/references/validation-and-recovery.md`](https://github.com/figma/mcp-server-guide/blob/main/skills/figma-use/references/validation-and-recovery.md) for persistent errors.

## Frequently Asked Questions

### Why can't my MCP client see any Figma tools?

The client cannot reach the Figma MCP server. Verify your [`mcp.json`](https://github.com/figma/mcp-server-guide/blob/main/mcp.json) configuration includes the correct server ID (`figma`) and URL (`https://mcp.figma.com/mcp`) as shown in the repository's [`README.md`](https://github.com/figma/mcp-server-guide/blob/main/README.md). Restart your editor after updating the configuration, as the UI may cache stale entries.

### How do I fix "Assets not loading" errors in localhost environments?

Enable "Allow insecure localhost connections" in your MCP client settings, or expose your local server via a tunnel like `ngrok`. The Figma MCP server returns absolute `localhost` URLs for assets; these must be reachable by the client without URL rewriting, as documented in [`skills/figma-implement-design/SKILL.md`](https://github.com/figma/mcp-server-guide/blob/main/skills/figma-implement-design/SKILL.md).

### What should I do if #get_design_context returns an error?

First, confirm the `fileKey` and `nodeId` are valid. Then run `#get_metadata` on the same node to gather additional context. Follow the error-recovery checklist in [`skills/figma-use/references/validation-and-recovery.md`](https://github.com/figma/mcp-server-guide/blob/main/skills/figma-use/references/validation-and-recovery.md): stop execution, analyze the error message, fix the underlying cause (network, permissions, or node existence), then retry the call.

### Where can I find the correct MCP server configuration for Figma?

The canonical configuration resides in the `figma/mcp-server-guide` repository's [`README.md`](https://github.com/figma/mcp-server-guide/blob/main/README.md) file under the **Connect to the Figma MCP server** section. This includes the exact JSON snippet for [`mcp.json`](https://github.com/figma/mcp-server-guide/blob/main/mcp.json) with the proper server ID, URL, and required headers.