How to Use Inspo MCP: Bring Design References and Screenshots into Claude Code or Codex UI Development

It is usually easy to ask Claude Code or Codex to “build a clean, polished, well-designed landing page” and get something that runs. The harder part is that the result often falls back to familiar gradient backgrounds, rounded cards, and oversized headlines, without the layout, rhythm, or visual hierarchy you actually wanted to borrow.

Inspo addresses this more specific problem: before the agent writes the UI, give it a set of design references from real websites. The official site currently lists 832 production websites, 2,320 page records with desktop and mobile captures, 68 reference components, and extracted information such as color palettes, typography, spacing, border radii, container widths, and page structure. It exposes this material to clients such as Claude Code and Codex through MCP.

Installing it, however, does not prove that the agent has seen the screenshots, and it certainly does not prove that the final page reflects them. A more reliable workflow is:

1. Connect Inspo MCP and confirm that the client is actually connected.
2. Ask the agent to retrieve references before it writes any code.
3. Check which page records and image URLs it received, and whether it actually read the images.
4. Turn the selected references into an explicit “reference contract.”
5. After implementation, inspect the real render, compare it point by point, and revise it.

The walkthrough below uses a hypothetical task: creating a developer-focused B2B product landing page for an existing project. It demonstrates the method; it does not mean this article has run or tested the project for you.

What Inspo MCP actually provides

Inspo is more than a screenshot search tool. According to its official MCP page and project repository, an agent can retrieve three types of reference material.

1. Pages and screenshots

search_screens can find real pages by natural-language description, visual style, industry, page type, color, light or dark mode, and page structure. Results may include:

• the page title, Inspo slug, and original website URL;
• desktop and mobile screenshot URLs;
• page thumbnails;
• color palettes, fonts, technology stack, and tags;
• analysis of the page’s overall characteristics and section structure.

When you need to study a particular candidate, use get_screen to retrieve a fuller record instead of pushing many candidates into the context at once.

2. Structured design systems

Each indexed website has a DESIGN.md derived from its page information. get_design_system can return typography, semantic colors, type scale, spacing, border radii, CSS variables, container widths, and similar details.

This data matters because “use this website as a reference” is too vague. Requirements such as “use a two-column hero, constrain the content container, give the primary button a high-contrast accent color, and keep generous space between sections” are much easier for an agent to execute consistently.

3. Reference components and code

Inspo also provides reference components for navigation, heroes, pricing sections, footers, and more. An agent can first use find_reference_components to locate a suitable component, then call get_reference_jsx to retrieve its JSX.

That does not mean you should copy an entire site unchanged. A better approach is to borrow the component composition and information hierarchy, then adapt them to the current project’s stack, brand, content, and interactions.

recommend is the best place to start. Give it a plain-language brief and it combines page structure, candidate websites, reference components, color palettes, and layout suggestions. On a first pass, asking the agent to call recommend and then inspect one or two candidates is usually more effective than searching through a dozen pages immediately.

Keep the model connection and Inspo MCP separate

Claude Code or Codex needs a working model connection for code analysis, editing, and reasoning. Inspo MCP supplies external design material. The two paths use different endpoints, authentication, and troubleshooting steps.

If you already use Claude Code or Codex through BetterToken, complete the model-side setup with the relevant documentation first:

• Claude Code setup guide
• Codex setup guide

Then configure Inspo separately. Do not use https://inspomcp.dev/api/mcp as the model Base URL, and do not give your BetterToken API Key to Inspo. Inspo’s hosted endpoint currently requires neither an account nor an API Key. BetterToken does not host Inspo, license third-party design material, or guarantee that an agent will read images or produce a particular UI result.

Before connecting it, confirm only that:

• Claude Code or Codex is installed and can complete ordinary coding tasks;
• the client can reach Inspo’s hosted endpoint;
• Node.js and npx are available if you plan to use the installer or local stdio mode.

Connect Inspo MCP

Inspo provides an automatic installer, and you can also use the MCP commands built into each client. On a machine with several AI coding tools, start with --dry-run so you can see which clients and configuration files would be changed.

Option 1: Use the Inspo installer

Check Claude Code without writing any configuration:

npx -y inspo-mcp install --dry-run --client claude-code

Install after reviewing the plan:

npx -y inspo-mcp install --client claude-code

Check Codex only:

npx -y inspo-mcp install --dry-run --client codex

Install after reviewing the plan:

npx -y inspo-mcp install --client codex

When --client is omitted, the installer detects installed copies of Claude Code, Codex, Cursor, VS Code, Windsurf, Claude Desktop, and Zed. The official Inspo MCP documentation says that it shows the plan and asks for confirmation first; --dry-run prints the plan without writing files, while -y skips confirmation.

Option 2: Add the hosted MCP directly

Inspo’s recommended hosted endpoint is:

https://inspomcp.dev/api/mcp

The official repository describes Inspo as read-only, but it is still an external third-party MCP. In a team environment, review the repository, data scope, and network policy before connecting it. “Read-only” is not a reason to skip a trust review.

According to the official Claude Code MCP documentation, remote services should be added over HTTP. To make Inspo available to all local projects, run:

claude mcp add --scope user --transport http inspo https://inspomcp.dev/api/mcp

Then check it:

claude mcp get inspo
claude mcp list

You can also enter this inside a Claude Code session:

/mcp

An Added message only means the configuration was written. Check claude mcp list for the actual connection state: Connected means it is connected. Resolve Failed to connect, Pending approval, or a disabled state before continuing.

The OpenAI Codex MCP documentation states that Codex supports Streamable HTTP and STDIO services. Add the remote MCP with:

codex mcp add inspo --url https://inspomcp.dev/api/mcp

List configured services:

codex mcp list

You can also use this in the interactive Codex interface:

/mcp

OpenAI’s current documentation says that Codex CLI, the IDE extension, and the ChatGPT desktop app share MCP configuration when they run on the same Codex host. After adding or changing the service, restart the current client or open a new session, then check whether Inspo appears.

stdio is only an alternative transport

If the client cannot conveniently connect to a remote URL, it can launch the stdio service through npx:

claude mcp add --scope user inspo -- npx -y inspo-mcp

codex mcp add inspo -- npx -y inspo-mcp

You can also add --local to the automatic installation command. This mode still retrieves the Inspo catalog from a CDN, so it is not the same as offline operation or full self-hosting.

On the first run, find references before asking the agent to code

A common mistake is to combine “find a reference” and “build the page” into one sentence:

Use Inspo to make me a good-looking landing page.

That leaves the agent to choose the references, decide what to borrow, and start coding immediately. Even if the result is poor, you will not know whether the search results were wrong, the screenshots never entered the context, or the implementation drifted away from the references.

A safer first prompt is:

Do not modify the code or start designing the page yet.

Use Inspo MCP to find 4 candidate references for a “developer-focused B2B AI API product landing page.”

Requirements:
- restrained, professional visuals, without large areas of colorful gradients;
- the hero must communicate the product value clearly and include one primary CTA;
- it may show a product interface or invocation flow, but should not look like a traditional corporate website;
- inspect both desktop and mobile references;
- start with recommend, then use search_screens, get_screen, or get_design_system only if needed.

For each candidate, return:
1. the page title, Inspo slug, and sourceUrl;
2. desktop and mobile screenshot URLs, if present in the tool result;
3. the macrostructure, main color palette, and typography;
4. 3 specific design ideas worth borrowing;
5. brand elements, copy, or decoration that should not be copied.

Finally, recommend only one primary reference and no more than two supporting references, and explain what each one will control. Do not write code yet.

The point of this prompt is not to elicit more adjectives. It is to obtain traceable page identifiers and evidence. You should see a concrete slug, the original website URL, screenshot URLs, and design data, rather than only a summary such as “modern, clean, and professional.”

How to confirm that the agent actually received the references

You can evaluate this in four layers. Passing one layer does not prove the next one.

Layer	Observable evidence	What it proves
MCP configured	Claude Code shows Connected, or Inspo appears in Codex’s MCP list	Connected confirms the Claude Code connection; a Codex list entry confirms configuration, while a successful tool call is needed to confirm service access
Tool returned data	The response includes a real slug, sourceUrl, colors, typography, page structure, and screenshot URLs	The agent called Inspo and received a structured record
Images were read	The agent explicitly opens screenshot URLs with an image-capable tool or uses an available image viewer, then describes concrete visual details	The agent did more than read text descriptions or links; thumbnails appearing in a result alone do not prove this
Page reflects the reference	The real render has explainable correspondence with the selected reference in structure, hierarchy, rhythm, and responsive behavior	The reference actually influenced the implementation

This distinction matters. Inspo’s response format always includes structured text and may include original image URLs. On supported paths, it can also place thumbnails into the tool result as native image content blocks. However, the project’s response-format implementation explicitly handles two other cases: if image retrieval fails, image blocks may be omitted while text and URLs remain; and a text-first configuration may return text only.

So “the agent returned a screenshot URL” does not prove that the model read the pixels. Send a verification prompt such as:

First prove that you received the primary reference. Do not start writing code.

Return:
- the Inspo tool names actually used in this session;
- the primary reference’s slug, sourceUrl, desktop screenshot URL, and mobile screenshot URL;
- 3 concrete visual facts observed from the desktop screenshot and 3 from the mobile screenshot, such as hero composition, navigation position, CTA alignment, image cropping, card arrangement, or collapse behavior;
- which conclusions came from the screenshots and which came only from Inspo’s text fields.

If the current client received only text or URLs and did not read the image pixels, explicitly write “image pixels were not read.” Do not infer visual details from the description.

The ideal result is not a long design critique. It should clearly separate elements that are visibly present in the image from conclusions supplied by structured data.

If the agent can only repeat the color palette, typography, and northstar description, ask it to open the screenshot URLs with whatever browser or image-reading tool is already available in the client. If the current client and model support visual input, download the screenshots and provide them as image attachments. If the model or provider path cannot process images, attaching a file will not change that: use Inspo for structure, color, and textual analysis, or switch to a compatible setup that supports visual input. MCP can return images, but that does not mean every client and model combination will consume them.

Turn the references into a “reference contract”

Once you have selected the candidates, do not stop at “use the feel of reference A.” Fix the responsibility of each reference and state what must not be copied.

Ask the agent to produce a contract like this:

Using the confirmed primary and supporting references, prepare a “reference contract” first. Do not modify the code yet.

Include:

1. Primary reference
- slug / sourceUrl:
- Responsible only for: overall page structure, hero composition, section rhythm

2. Supporting reference A
- slug / sourceUrl:
- Responsible only for: type hierarchy, body width, whitespace

3. Supporting reference B (only if genuinely necessary)
- slug / sourceUrl:
- Responsible only for: one specific component or mobile collapse behavior

4. The current project must retain
- the existing technology stack, routing, and component conventions
- the real product copy, feature boundaries, and brand colors
- existing interactions, accessibility requirements, and performance requirements

5. Explicitly prohibited
- do not copy the source website’s logo, brand name, illustrations, photos, or original copy
- do not reproduce the entire website pixel for pixel
- do not invent features that the current product does not have just to match the reference

6. Acceptance criteria
- in a common desktop viewport, the hero fully communicates the title, explanation, CTA, and main visual
- the information hierarchy follows the primary reference, but the content belongs to the current product
- mobile has a deliberate rearrangement strategy, not merely a scaled-down desktop layout
- section spacing, container width, type hierarchy, and button priority follow inspectable rules

The contract turns inspiration into constraints. The primary reference controls the overall structure; supporting references solve local problems. More references are not automatically better. If five websites all control the colors, typography, cards, and hero, the result often collapses back into a generic AI-style page with no clear priority.

Let Claude Code or Codex implement the page

After confirming the references and acceptance criteria, let the agent inspect the repository and modify the code. The prompt below intentionally does not hard-code npm run dev, a framework directory, or a test command. The agent should determine those from the project rather than guess.

Start the implementation now.

First inspect the current repository’s technology stack, page entry points, design variables, reusable components, and available scripts. Then modify the page according to the confirmed “reference contract.”

Implementation requirements:
- use the existing framework, component system, and dependencies; do not add a new UI framework unless it is genuinely necessary;
- keep the real product content and functionality, and do not copy brand assets or copy from the reference websites;
- translate the references into this project’s own layout, CSS variables, and components;
- implement desktop and mobile deliberately; do not leave mobile until the end and rely on automatic scaling;
- fix overall structure, information hierarchy, and spacing before decorative details such as shadows and border radii;
- do not overwrite existing project components merely because Inspo provides JSX.

Before modifying files, briefly explain:
1. which files you plan to change;
2. which component or style rule each reference point will map to;
3. which existing content must remain unchanged.

After completion:
- run the repository’s existing formatter, type checks, or tests;
- start the available local preview;
- list the files actually changed;
- output a “reference point → implementation location” mapping;
- do not judge the result only with phrases such as “more modern” or “more premium.”

If the project already has design tokens, ask the agent to update tokens or semantic variables first instead of scattering hard-coded colors and dimensions across multiple components. That makes it much easier to correct the page’s overall rhythm in the next iteration.

The final judgment must be based on the real render, not the code diff

A page that compiles only proves that the code runs. To judge whether it reflects the references, inspect the actual page.

Inspo pages usually include desktop and mobile captures. Its official Colophon says the archive uses widths of 1440 pixels and 375 pixels. You do not need to match the exact heights, but inspecting your implementation at similar widths makes the overall structure and mobile rearrangement easier to compare.

If Claude Code or Codex already has a browser, Playwright, or another screenshot tool configured, ask the agent to open the local page. Otherwise, open the preview yourself, capture desktop and mobile screenshots, and give them back to the agent.

Ask it to review them in this format:

Compare:
- the confirmed primary reference’s desktop and mobile screenshots;
- real screenshots of the current page at approximately 1440px and 375px widths.

Do not redesign or change code yet. First output a difference table:

| Checkpoint | Observable evidence in the reference | Current implementation | Difference | Recommended change |
| --- | --- | --- | --- | --- |
| Hero structure |  |  |  |  |
| Title and CTA hierarchy |  |  |  |  |
| Container and whitespace |  |  |  |  |
| Type hierarchy |  |  |  |  |
| Color and contrast |  |  |  |  |
| Component arrangement |  |  |  |  |
| Mobile rearrangement |  |  |  |  |

Then select only the 3 differences with the greatest impact and fix them. Re-render and review after the changes. Do not introduce a new design direction in the same pass.

Good feedback should be observable and actionable. For example:

• Do not say: “The hero still does not feel premium enough.”
• Say: “The primary reference shows the headline, CTA, and product interface within the first viewport. The current page has too much vertical whitespace, so the product interface falls below the fold. Reduce the hero’s vertical spacing, constrain the headline width, and bring the main visual into a typical desktop viewport.”

Another example:

• Do not say: “The mobile version does not look enough like the reference.”
• Say: “On mobile, the reference presents the headline and CTA before a single-column product card. The current implementation preserves the desktop two-column layout, which squeezes both text and image. Switch to one column on mobile and keep the CTA before the main visual.”

Fixing only a few high-impact differences in each pass usually converges faster than repeatedly asking the agent to “make it look better.”

Common problems

The configuration command succeeded, but the agent cannot find Inspo

Check the client state before reinstalling anything.

Claude Code:

claude mcp get inspo
claude mcp list

Codex:

codex mcp list

Confirm that the endpoint has no extra characters, then restart the client. If Claude Code uses a project-level .mcp.json, you may also need to approve the service in a trusted workspace.

MCP is connected, but the agent never calls Inspo

Separate retrieval from coding. Explicitly require the prompt to “call Inspo first, return the slug, sourceUrl, and screenshot URLs, and do not modify code until the references are confirmed.” Also verify in /mcp that the service is enabled.

The agent returned a page description, but no image is visible

The call may have returned text only, thumbnail retrieval may have failed, the client may not display MCP image blocks, or the model path may not process images. Check whether desktop and mobile screenshot URLs are still present, and ask the agent to state clearly whether it read the image pixels. If the current client and model support visual input, open the URLs with a browser tool or provide the screenshots as attachments. For a text-only model, use the structured data or switch to a setup that supports visual input.

The page still looks like a generic template

The solution is usually not to find ten more references, but to narrow the brief: one primary reference controls the macrostructure, one supporting reference controls typography and whitespace, and at most one more controls a specific component. Put those roles into the reference contract and require the agent to map each reference point to a code location.

The context is too large and the agent starts mixing up references

Use recommend to obtain candidates, then call get_screen or get_design_system only for the one or two you select. Do not load many full page records and component sources at once. Call get_reference_jsx only when you need a particular component.

The original website no longer matches the Inspo screenshot

Inspo stores page material from the time of capture, while the original website may later be redesigned. Compare against the selected Inspo screenshot and record. sourceUrl is for tracing the source; it should not be assumed to remain visually identical to the archive forever.

The goal is not merely to “install an MCP,” but to build an evidence chain

The value of Inspo MCP is not that it automatically decides what good design is. It turns “I want this kind of feel” into traceable pages, screenshots, design data, and component references.

A reliable UI development pass should leave four kinds of evidence:

1. the client confirms that Inspo is connected;
2. the agent returns specific pages and design material;
3. you can confirm that it read the screenshots, or it honestly states that it received text only;
4. the final render can explain, point by point, which structural, hierarchical, and responsive rules came from the references.

Once retrieval, confirmation, implementation, and verification are separated, Claude Code or Codex is no longer just “making a nice-looking page by feel.” It is working inside a design context that you can inspect, correct, and reuse.