# 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 a reference, inspect its real evidence, and adapt it to the user's 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. Free access does not unlock the paid website or Vault. Plans and monthly MCP credits: https://www.details.so/pricing.md

## 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): full evidence for one inspiration by stable ID or slug: static image or seven ordered video frames, tags, factual description, source URL, source-verified code excerpts when available, and an implementation brief. Call this before implementing anything from a reference.
- `read_inspiration_bundle`: bounded, versioned reads of instructions and selected source files; transfer mode supports hash-checked file saving without dumping code into chat.
- `read_inspiration_source` (Pro and above, when source evidence is available): 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.

## When the user pastes a Details link, slug or inspiration ID
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.
2. A Details inspiration URL (`https://www.details.so/inspo/<slug>`), a slug, or a stable inspiration ID is already an explicit selection. Call `get_inspiration` with it directly; do not run `search_inspirations` first.
3. Follow the implementation brief in the response: inspect every returned frame or image, read the cited source excerpts, and build the recorded interaction, adapting only copy, assets and styling to the user's project.
4. For a Vault link (`https://www.details.so/vault/<slug>`) call `get_vault_resource` with the slug and `content: "implementation"`.

## 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 Code

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.

### 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.
- Terms: https://www.details.so/legal/terms · Privacy: https://www.details.so/legal/privacy