# Details MCP

Details is a hand-curated library of website design inspiration (Inspo) and production-ready implementation resources (Vault). The Details MCP server exposes both to AI coding clients so an agent can find references, inspect their real evidence, and turn what the user likes into their own project.

- Server URL: https://api.details.so/mcp
- Transport: remote Streamable HTTP, JSON responses, no server-to-client streaming.
- Authentication: OAuth in the browser with the user's Details account. Discovery metadata is served at `/.well-known/oauth-protected-resource`.
- Access: any paid Details plan. Pro receives the Inspo tools; Max, Team and Lifetime receive the Inspo and Vault tools. Free accounts can connect and use Inspo tools with a one-time allowance of 20 credits while free access is enabled. Free access may be turned off, including unused credits, and credits never refill, so never promise it: when a tool answers that free access is turned off, tell the user and link the plans. Free access does not unlock the paid website or Vault. Plans and monthly MCP credits: https://www.details.so/pricing.md

## What a user can do with a reference
- **Build it as is**: Rebuild the reference in the user's project with their own content, keeping its layout and motion.
- **Use one detail**: Take a single detail the user names, such as a hover effect, a scroll transition or a layout, and leave the rest.
- **Explore variations**: Show several different takes on the reference or on one of its details, then build the one the user picks.
- **Combine references**: Mix parts of several references, such as the layout of one with the motion of another, or use a different reference for each section.

Propose these moves yourself instead of waiting to be asked. After you present search results, end with one short question that offers them: build one as is, use a single detail from one, explore variations of one, combine several (for example the layout of one with the motion of another), or refine the search. Add a concrete idea or two from the evidence, for example pairing two of the numbered results. When the user hands you one reference without saying what they want, ask the same about that reference. The user decides: never pick a result for them or start building from your own suggestion.

## Remix: when the user pastes a Details reference, link or ID
Every inspiration page on details.so has a Remix button. It copies these two lines, which the user pastes into their AI with or without a request of their own:

```
<title> (Details ID: <id>)
If the Details MCP isn't connected yet, follow https://www.details.so/mcp.md
```

1. Check that the Details MCP is connected in the current client. If not, follow the setup for that client below and ask the user to approve the connection. Keep the ID and continue with step 2 once the tools are available; if the client only loads new tools in a new session, ask the user to paste the Remix text again there.
2. The ID is already an explicit selection. Call `get_inspiration` with it directly; do not run `search_inspirations` first. The same goes for a slug and for a Details inspiration link (`https://www.details.so/inspo/<slug>`): pass the slug, the part after `/inspo/`.
3. If the user did not say what they want, do not start building. Say in a sentence or two what the reference shows and ask what they would like to do: build it as is, use a single detail, explore variations, or combine it with other references. Wait for the answer; when they want one detail, let them name it.
4. Then follow the instructions returned with the reference: read `instructions.md` first, inspect every returned frame or image and the cited source excerpts, and keep the recorded behavior of what the user chose while adapting copy, assets and styling to their project.
5. For a Vault link (`https://www.details.so/vault/<slug>`) call `get_vault_resource` with the slug and `content: "implementation"`.

## When the user asks you to find references
1. Call `search_inspirations` with the user's own words in `query` and what you know about their project in `projectContext` and `projectBrief`.
2. Present every result as a numbered link to its Details page, in the returned order, without choosing one for the user.
3. End with the question that offers the next moves, then wait.
4. Before you build, vary or combine anything, call `get_inspiration` for every reference involved. A search result is a preview, not evidence.
5. For other, rejected or refined results, search again with the previous `nextSearchArguments`. Never replace Details results with images from the web.

## Variations and combinations
Variations: when the user asks for variations, start from the evidence returned by get_inspiration, never from a search preview. Prepare three or four unless the user gives a number. Each one keeps what the user liked recognizable and changes one clear thing, such as the motion, the layout, the timing or the visual style; name each after what changed. Show them side by side as quick previews in a form the host supports (one preview page, separate components or rendered snippets), outside the user's real pages, and say they are sketches for choosing, not verified matches of the reference. Ask which one to build or which parts to mix, and remove the other previews unless the user wants them kept. Build the chosen one with the full implementation workflow: record its deliberate changes as user-approved adaptations and keep everything else faithful to the reference.

Combining: when the user combines references, call get_inspiration for every one of them and state which part comes from which, for example the layout of one and the motion of another. Keep each borrowed part faithful to its own evidence. Where two parts cannot work together, such as two scroll drivers or two owners of one layout, explain the conflict and let the user choose instead of quietly dropping either. Independent sections keep one reference each, from different source websites.

## Tools
- `search_inspirations` (Pro and above): natural-language search over the Inspo library. Pass the user's design constraints nearly verbatim in `query`; put one short factual sentence about the business and page in `projectContext`. When known, also pass `projectBrief` with the business type, section purpose, and compatible related industries. Preserve rejected appearance as a rejection, not an industry request. Returns up to ten numbered candidates. For other, rejected, or refined results, reuse the same Details connection and the previous `nextSearchArguments`, preserving the project brief and cumulative excluded IDs with offset 0; change only the requested design direction. This returns another gallery. If access fails, report it instead of switching to standalone web images. Present them and wait for the user to choose unless the user explicitly delegated the choice.
- `get_inspiration` (Pro and above): the evidence for one inspiration by stable ID or slug: one static image or seven ordered video frames, plus a list of versioned evidence files (instructions, source excerpts, CSS and data). Read `instructions.md` first. Call this before building anything from a reference, preparing variations or combining references.
- `read_inspiration_bundle` (Pro and above): bounded, versioned reads of the instructions and evidence files listed by `get_inspiration`; transfer mode supports hash-checked file saving without dumping code into chat.
- `read_inspiration_source` (Pro and above): reads the same evidence files and, when source was captured, bounded character pages within up to 400 numbered source lines; follow nextOffset before advancing lines.
- `search_vault` (Max, Team and Lifetime): search production-ready Vault resources such as accordions, text reveals, page transitions and buttons. Use only when the user asks for the Vault or a packaged Details implementation.
- `get_vault_resource` (Max, Team and Lifetime): the canonical implementation prompt (`content: "implementation"`), documentation, or extra material for one Vault resource by stable ID or slug.

## Public markdown pages
Every public Details page has a markdown twin at the same path plus `.md`, for example `https://www.details.so/inspo/<slug>.md`, `https://www.details.so/inspo/category/<slug>.md` and `https://www.details.so/vault/<slug>.md`. They contain public metadata only (title, website, tags, media URLs, related pieces). The frames, source excerpts, behavior summaries, prompts and code are only available through the MCP tools above. Index: https://www.details.so/llms.txt

## Setup

### Claude

1. **Add Details to Claude Code** Run this once in a terminal to register Details for your user account.

```
claude mcp add details --scope user --transport http https://api.details.so/mcp
```

2. **Open the MCP menu** Start Claude Code, enter the command below, then choose Details.

```
/mcp
```

3. **Approve the connection** Choose Authenticate and sign in to your Details account in the browser.

4. **Ready to use** Return to Claude Code and start searching Details.

### ChatGPT

1. **Install the Details.so plugin** Open the official Details.so plugin in ChatGPT and choose Install plugin. [Open in ChatGPT](https://chatgpt.com/plugins/plugin_asdk_app_6aa41d5122f48191865e1b4041becce7)

2. **Connect your account** Continue to Details when ChatGPT asks, then sign in and approve access.

3. **Ready to use** Start a new chat and ask ChatGPT to search Details.

### Cursor

1. **Open MCP settings** In Cursor, open Settings → Tools & MCP and choose New MCP Server. Use global settings for every project, or project settings for one workspace.

2. **Add the Details server** Paste this configuration into your mcp.json file and save it.

```
{
  "mcpServers": {
    "details": {
      "url": "https://api.details.so/mcp"
    }
  }
}
```

3. **Connect your account** Back in Tools & MCP, find Details, choose Connect, and approve access in the browser.

4. **Ready to use** Details is now available to Cursor in the scope you selected.

### Codex

1. **Add the Details MCP server** Run this once in a terminal to register the remote server.

```
codex mcp add details --url https://api.details.so/mcp
```

2. **Start the login flow** Run the login command to open Details authorization in your browser.

```
codex mcp login details
```

3. **Approve the connection** Sign in to Details, review the request, and choose Continue.

4. **Ready to use** Return to Codex. Start a new session if it was already open during setup.

### v0

1. **Open MCP connections** From the chat input, open the add menu, choose MCPs, then select Add MCP.

2. **Enter the server details** Name the connection Details and paste the remote server URL.

```
https://api.details.so/mcp
```

3. **Approve the connection** Select OAuth when prompted, then sign in and approve Details access.

4. **Ready to use** Details is now available from your v0 chat.

### Other

1. **Find your client's MCP settings** Open the integrations or MCP area in your AI client.

2. **Add the server URL** Create a remote HTTP MCP server named Details and paste this address.

```
https://api.details.so/mcp
```

3. **Approve the connection** Use OAuth when available, then sign in and approve access to Details.

4. **Ready to use** The Details tools should now appear in your client.

## Limits and privacy
- Tool calls are metered per account with a daily cap and monthly credits on paid plans. Free accounts have 20 lifetime credits shared across clients while free access is enabled: search costs 2, inspection costs 3.
- Admitted searches and inspections spend credits even when repeated, a search returns no results, or retrieval fails. One assistant response may call several tools. There are no refunds or free-credit refills.
- Free source and bundle reads cost 0 and require a previous successful charged free inspection of the same reference by this account. Those references remain readable at 0 credits while free access is enabled. Turning free access off also stops source reads without disconnecting the account.
- Details logs the tool name, account and timestamp of each call for metering. Query text is not stored beyond request handling. Search text, `projectContext` and `projectBrief` are sent to OpenAI to rank matching references, so include only what the task needs and never secrets or unrelated personal data.
- Terms: https://www.details.so/legal/terms · Privacy: https://www.details.so/legal/privacy
