FAQ and troubleshooting
Answers to the common questions about the MCP server, the dataset and the widget, and fixes for the problems people hit most often.
Frequently asked questions
What is The Face Analysis MCP server?
A free, read-only Model Context Protocol server that lets an AI assistant look up face measurement statistics from 102 faces, the face, eye, lip and nose type rules, the methodology and its limits, and run the site's seven-rule face shape classifier on four distances. The code is MIT-licensed and open source; the aggregate data is CC BY 4.0.
Does it analyze photos?
No. The server takes no photo. Photos are measured in the visitor's browser by the free face shape tool or the embeddable widget. The MCP server gives an assistant the numbers, the rules and a classifier for four measured distances.
Do I need an account or an API key?
No. The hosted server needs no sign-up, key or credit balance, and all seven tools are read-only.
Hosted or local: which should I use?
Use the hosted URL unless you need to work offline or want to inspect the code you run. Both expose the same seven tools. The hosted server needs no Node.js and works in ChatGPT and in Claude's custom connectors, which cannot launch a local npx process.
Which AI clients does it work with?
Any client that speaks MCP: Claude (claude.ai, Desktop and Claude Code), ChatGPT through Developer mode connectors, Codex, Cursor, VS Code, Gemini CLI and others. The setup commands for each are on this page, taken from the clients' own documentation.
Can I cite the numbers it returns?
Yes. The aggregate numbers are licensed CC BY 4.0: cite The Face Analysis, link the statistics page, and credit the Face Research Lab London Set the photos come from. The get_citation tool returns the exact text.
How accurate is the face shape classifier?
We claim no accuracy figure. The 102 reference faces have no labelled face types, so the thresholds spread the faces sensibly but are not validated against a ground truth. A face near a boundary can flip between two shapes with a small change in the photo, which is why the tool returns the matched rule along with the four ratios.
Is the code open source?
Yes. The server, the dataset package and the embeddable widget are MIT-licensed code in public repositories at github.com/The-Face-Analysis. The aggregate data is CC BY 4.0.
Troubleshooting
The tools do not appear in my client.
Quit the client completely and reopen it; many clients read their MCP configuration only at start-up. Then check the JSON or TOML syntax: a trailing comma or a missing quote silently drops the server. In Claude Code claude mcp list shows whether it is connected, in Cursor the MCP settings page does, and in VS Code the status line above the server in .vscode/mcp.json does.
npx is not found or will not start.
A local install needs Node.js 18 or newer (node --version). On Windows, if npx is missing, install npm globally with npm install -g npm. With the hosted URL you do not need Node.js at all.
Opening the MCP address in a browser shows 405.
That is expected. The server accepts only the POST /mcp request MCP clients send. To see that it is running, open https://mcp.thefaceanalysis.com/health (it answers ok) or run the curl command on this page.
ChatGPT or Claude does not show the custom connector option.
Custom connectors depend on your plan and your organization's settings. In ChatGPT, Developer mode must be on, and on Business, Enterprise, Team and Edu accounts an admin has to allow connectors. Clients rename menus: search their help pages for custom connector to find the current path.
A tool returns an error.
The input was invalid, for example get_face_type was given a type name that does not exist. The error message lists the valid options. For classify_face_shape, all four distances must be greater than zero and in the same unit.