I Gave an AI Three Design References. It Invented a Fourth.

Secret MCP started with a familiar frontend problem: I opened too many tabs.

I saved one award-winning airline site for its navigation, another for its pacing, and a third for the way it handled mobile. Then I gave the screenshots to an AI coding agent and asked for an implementation plan.

What came back looked polished. It was also impossible to trust.

The palette seemed to belong to one site. The header resembled another. The mobile behavior was not visible in any of them. By the time the agent flattened everything into “a clean, modern experience,” I no longer had three references. I had a fourth design with no clear source.

That failure is why I built Secret MCP.

Secret MCP searches GDWEB from an MCP client and turns every selected website into its own evidence-backed frontend plan. One reference goes into one model request. One implementation-ready DESIGN_INDEX comes out.

Search, screenshots, measurements, responsive observations, and file output happen in the same workflow. The result is not another chat answer to scroll past. It is a local document that a developer—or the next coding agent—can build from.

Here is the difference I wanted in practice:

Before
search → open tabs → save screenshots → write a giant prompt → untangle the answer

With Secret MCP
ask once → find references → analyze each separately → save separate build plans

I will show the real output in a moment. First, it helps to explain why I made this an MCP server instead of another screenshot-to-code page.

Why MCP, though?

A script could download the images. A web app could display them. Neither would solve the handoff I cared about.

If MCP is new to you, the useful definition is simple: it gives an AI application a standard way to call tools outside the model. In this case, it connects a sentence such as “find three aviation references” to a real search-and-analysis pipeline.

That changes the experience in four ways.

• The agent can discover the tool. Secret MCP describes what it accepts and what it returns, so you ask for an outcome instead of operating the pipeline by hand.
• The research stays beside the project. The same client that helps plan or code the site can call the design tool and receive the saved document paths.
• The workflow is repeatable. Search filters, image preparation, evidence labels, the document structure, and output naming do not depend on remembering yesterday's prompt.
• The result can feed the next tool. A saved DESIGN_INDEX can guide a coding agent, a Figma workflow, component selection, or later browser QA.

The current version also lets the connected MCP client perform the model request. Secret MCP does not need its own LLM API key; it asks a compatible client to generate the document through MCP Sampling. That choice comes with a compatibility tradeoff, which I will be honest about below.

What this produced in a real project

Here is the result first.

AEROFLOW is a new aviation website with its own name, copy, imagery, and functionality. Its structure was built from one of the design specifications produced in a preserved Secret MCP run.

That run began with three aviation references from GDWEB. A request can be as direct as:

Find three recent aviation websites on GDWEB. Analyze them separately and save an implementation-ready design index for each one.

Secret MCP searched inside the server, prepared the desktop and mobile evidence, and made three separate model requests. It wrote three separate Markdown files. Only after the first file was saved did the second reference enter the pipeline.

For the Korean Air reference, the output was not “use a premium blue palette and generous whitespace.” It described the visible page structure, navigation, section geometry, measured colors, component candidates, responsive evidence, implementation order, and QA criteria. Claims that could not be verified from the screenshots were not presented as facts.

This was the moment the project became useful to me. I could hand the document to another coding session without replaying the original research conversation. And when something looked wrong, I could open the viewer and trace it backward instead of starting over.

The real alternative is a screenshot folder

It is tempting to compare every MCP server with every other MCP server. That is not how I choose tools in practice.

The workflow Secret MCP replaces is manual: search for sites, open each result, save images, paste everything into one conversation, explain the desired output, and then reconstruct where the answer came from. It works. I did it for a long time. It just gets fragile when the number of references or the depth of the handoff grows.

Other MCP tools solve adjacent jobs well:

• If I already have an approved Figma file, I would use the Figma MCP server to bring frames, variables, components, and design-system context into development.
• If I need an agent to navigate, click, or inspect a live page, I would use Playwright MCP.
• If I need broad web, news, image, or local search, Brave Search MCP is built for that surface.
• If I want to search a component catalog and install or generate UI, I would use 21st MCP.

Secret MCP starts earlier than those implementation steps. Use it when you have public website inspiration but no design source of truth yet—and the thing you need next is a full-page plan with evidence behind it.

That also makes the tools complementary. A workflow can begin with Secret MCP for reference research, move through Figma or a component library for design and implementation, and finish with browser automation for QA.

What I actually wanted the document to do

I did not want a design critique. I wanted a build handoff.

Each DESIGN_INDEX begins with the evidence it was allowed to use and then turns the visible design into decisions a developer can act on:

• a page and route inventory
• header, navigation, section, and footer structure
• visible coordinates and spatial relationships
• representative colors and reusable design tokens
• component boundaries, states, and asset guidance
• desktop-to-mobile observations and unknowns
• accessibility notes, implementation tasks, acceptance criteria, and QA tolerances

Every important statement carries one of four labels:

• MEASURED: derived from pixels or recorded coordinates
• OBSERVED: directly visible in the supplied evidence
• INFERRED: a reasonable implementation decision, but not directly visible
• UNKNOWN: something a static screenshot cannot establish

Those labels are deliberately unglamorous. They stop a confident sentence from quietly becoming a fact.

How it avoids inventing the fourth design

The unusual part of Secret MCP is not the search. It is where the search results are allowed to go.

If the server returned three references to the host and asked the host to analyze them later, all three could already be sitting in one conversation. The mixing would begin before the analysis did.

So the generation tool keeps the result queue inside the server. For each reference, it prepares only that work's images and metadata, sends one sampling/createMessage request with includeContext: none, saves the response, and then advances to the next item.

reference A → request A → DESIGN_INDEX_A.md → saved
reference B → request B → DESIGN_INDEX_B.md → saved
reference C → request C → DESIGN_INDEX_C.md → saved

The fixed contract, evidence manifest, and generation log are preserved with each work. A smoke test checks that the number of results matches the number of model requests, that every request contains exactly one reference ID, and that each response creates a separate file.

That is an observable boundary, not a magical privacy claim. It does not say what an external model provider retains. It says exactly what Secret MCP sends in each request and leaves the artifacts needed to verify it.

A few ways to use it

Start from a blank page. Ask for recent references in a category and generate one plan before touching the component tree.

Find a recent GDWEB reference for a technology landing page. Create one DESIGN_INDEX I can use to plan a new React site.

Explore several directions without blending them. Generate three documents independently, then compare the finished plans after each reference has been described on its own terms.

Find three finance websites from 2025–2026. Keep their analyses separate. After the files are saved, return only their paths and statuses.

Give another agent a durable handoff. Point a coding session at one DESIGN_INDEX instead of reattaching the screenshots and retelling the design intent.

Read DESIGN_INDEX_gdweb-<id>.md. Build the page in this repository with new branding and content. Treat UNKNOWN claims as decisions to confirm, not facts.

Audit a bad result. Open the local viewer, select the reference, and move from the questionable paragraph back to its contract, image tile, crop coordinates, and generation event.

You do not have to run the expensive path every time. search-gdweb-designs returns a lightweight reference list when discovery is enough. generate-gdweb-design-indexes performs the evidence preparation and document generation. The server also exposes general web-search and page-content tools for supporting research around a project.

Try one reference, not three

Secret MCP is open source under MIT and published on npm as secret-design-mcp. It requires Node.js 20.19 or later.

Add it to a compatible MCP client:

{
  "mcpServers": {
    "secret-mcp": {
      "command": "npx",
      "args": ["-y", "secret-design-mcp"],
      "env": {
        "DESIGN_INDEX_OUTPUT_DIR": "/absolute/path/to/design-index",
        "SECRET_MCP_WEB_ORIGIN": "http://127.0.0.1:4317"
      }
    }
  }
}

Then ask for one design you can evaluate quickly:

Find one recent GDWEB website in a category you know well. Generate its DESIGN_INDEX and return the saved file path.

Open the file and ask one question: could another developer begin planning from this without seeing my original chat?

One limitation to check first

Version 0.6.0 requires a client that supports MCP sampling/createMessage. If the capability is unavailable, Secret MCP stops with an explicit error instead of falling back to a combined prompt.

Sampling was deprecated in MCP protocol version 2026-07-28. It remains available during the protocol's deprecation window, but the project needs to migrate to direct provider calls. The rule I intend to preserve is more important than the mechanism: a fresh model request and a fresh workspace for every reference.

Secret MCP is not a pixel-cloning tool, and the preserved aviation run is not a benchmark proving that it produces better websites. It is a working, inspectable pipeline for moving from public design research to a frontend specification without losing track of the source.

That is the whole reason it exists.

If that is a gap in your workflow, try Secret MCP on GitHub. If the document is useful, a star helps other developers find it. If it gets something wrong, open an issue with the reference ID, evidence tile, and section that failed. That is feedback I can trace all the way through the run.