MCP, and getting Figma into your directory

What MCP is

An agent can read the files you point it at. It cannot, on its own, open your Figma file, query your database, read your issue tracker, or fetch a page. Those live behind APIs, and every API is different.

MCP — the Model Context Protocol — is a standard shape for that connection. A tool vendor writes one server; any agent that speaks MCP can use it. Without it, every agent needs a bespoke integration with every tool, which is why for two years agents could write beautifully about your design file and never actually see it.

Your directory is what the agent knows. MCP is what it can go and get. Keep the two straight and most of the confusion disappears.

A server exposes three kinds of thing, and the distinction matters more than it sounds:

A server is a door into a system, and doors work in both directions. Connecting one to a shared team file means an agent acting on your instruction can change something other people depend on. Connect read-only where read-only is offered, and never connect a client’s file to an experiment.

Connecting one

The mechanics differ by client and they change — check current documentation rather than trusting a screenshot from a blog post. The shape is always the same three moves.

• The client holds the config. Claude Desktop, Claude Code, Cursor and the rest each keep a list of servers you have enabled. That list belongs to your machine, not to your project.
• The server runs somewhere. Either locally as a small program on your computer, or remotely as a hosted service you authenticate to. Local servers can see your filesystem; remote ones cannot.
• Auth is a grant, not a setting. When a server asks for access, read what it is asking for. "Full account" and "this one file, read-only" are very different answers to the same dialog.

Credentials never go in the project directory. Not in a config file you commit, not in a note, not temporarily. The client stores them. That rule is from the first guide and it does not bend here.

But do record what you connected

Which servers an agent had access to is part of how your work was made, which makes it process documentation. One file, five lines, no secrets in it:

What earns its place in twelve weeks

You can connect a dozen servers. Do not. Each one adds surface the agent will wander into, and an agent with fifteen tools spends its attention choosing between them.

The Figma connection

The Figma MCP server lets an agent read a file you have open or have linked. Given a node — a frame, a component, a page — it can return the layer structure and layout, the variables and styles that node uses, a screenshot of it, downloadable assets, and a code draft of the layout.

That last one is the seductive part and the one to be most careful with. It is a draft. It is not your design system.

Figma is the source of truth for the design. Your directory is the source of truth for the decisions. Neither one gets to overwrite the other.

Everything below is a consequence of holding that line. The failure it prevents is specific and common: by week ten you have tokens in your repo, different tokens in your Figma file, generated components built from a third set, and no way to say which is the design.

Rules for extraction

Seven. They are short because they get applied under deadline pressure.

• Extract by node, never "the file." Select the frame, copy its link, hand over that. A whole-file request returns an average of everything you have ever drawn, including the abandoned page.
• Variables for building, screenshots for judging. If you want the system, pull the variables and styles — the named things. If you want to evaluate how it looks, pull the image and look at it. Asking an agent to infer a colour scale from a picture is asking it to guess.
• Generated code is a draft and lands in the draft folder. 03_build/prototype/, never design-system/. Code that arrives already looking finished is exactly the material the Lie question exists for.
• Log every extraction. File key, node id, date, what came out, what you did with it. An extraction is a snapshot of a file that keeps moving. Six weeks later, "where did this spacing scale come from" has to have an answer.
• Assets keep their names. One assets/ directory, exported names preserved. Renaming in transit breaks the only link between the thing in your build and the layer it came from.
• Change one side at a time. In a given week you are either editing the Figma file or editing the extracted tokens — not both. Two-way drift is unrecoverable without a diff nobody is going to run.
• When they disagree, the file wins and you re-extract. Do not patch the extraction to match. Patching is how the repo quietly becomes the real design system while everyone still believes Figma is.

Where it lands

The design system folder from the first guide, filled in. Small. A twelve-week system is tokens, a type scale, colour, and three or four components that actually appear in the prototype.

EXTRACTION.md, one entry

That last paragraph is the whole reason the log exists. It is also, word for word, the kind of thing your process book needs and nobody can reconstruct in December.

Three lies this connection tells

Named, so you recognise them when they arrive. All three look like correct output.

• Tokens that do not exist. An agent reading a rendered frame will report colours it can see, including ones produced by opacity, overlay or a blend. They come back with plausible names. Check every token against the variables panel, not against the render.
• Layout flattened to fixed numbers. Auto-layout, constraints and responsive rules routinely come out the other side as hard pixel values that happen to look right at the width you extracted. The layout is now a photograph of your layout.
• Components that are not your components. Generated code often rebuilds an instance as fresh markup rather than referencing the component. It looks identical and shares nothing, so the next change has to be made twice.

You have an advantage the agent does not: you know what is in your own file. That is the Catch — the check only a person who drew it can perform, and it takes about ninety seconds.

What does not get connected

• Files that are not yours. A client file, a studio file, anything under an NDA or a working agreement. Access you were given is not access you can delegate.
• Anything holding participant data. Same rule as the project directory, for the same reason. Consent was for your research, not for a third-party service.
• Write access you do not need. If read-only does the job — and for this course it does — take read-only.

Back to the directory

MCP widens what the agent can reach. It does not change where the project lives. Every extraction still ends the same way: a file in a numbered folder, a line in a log, and a decision recorded with the reason attached.

← Setting up a project for an agent