Troubleshooting MCP Server Connection Issues: Complete Diagnostic Guide

Most Figma MCP server connection failures stem from three layers: incorrect server configuration in 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 or mcpServers configuration against the canonical snippet in [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#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. 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:

   #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): 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:

#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:

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

Successful response excerpt:

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

Diagnose Asset Loading Issues

Check if image URLs are accessible:

#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:

// 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.
• 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 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 configuration includes the correct server ID (figma) and URL (https://mcp.figma.com/mcp) as shown in the repository's 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.

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: 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 file under the Connect to the Figma MCP server section. This includes the exact JSON snippet for mcp.json with the proper server ID, URL, and required headers.

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