MCP

1. Get a tokenThe key icon in the library, then Create. Copy it: it is shown once.
2. ConnectOne command for Claude Code, or a JSON block for Cursor and VS Code. Nothing to install.
3. Check itAsk your assistant to call whoami and library_status.

What the Design Stream MCP is

MCP, the Model Context Protocol, is how an AI assistant calls tools that live outside it. The Design Stream MCP server is hosted: your client connects to https://designstream.dev/mcp over HTTPS and sends your API token with every request, so there is nothing to install and nothing to update.

It answers from the library: real websites captured whole and split into sections — hero, pricing, testimonials, FAQ, footer and more — each with the design system read off the live page and its SEO metadata, plus your boards. What it returns is read out of a capture: the colours, type ramp, spacing, radii and CSS variables were measured on the page on its capture date, not inferred. The exception is each section's caption and user story, which a vision model wrote so that search works — good enough to rank by, not something to quote as fact about the page.

Before you start

• An invitation. Design Stream is private and has no public sign-ups. MonoMind adds your email, an invitation arrives, and you sign in at auth.designstream.dev.
• An admin or team account. The MCP reads the library, and only those two roles may.
• An MCP client that connects to a remote server with a header, such as Claude Code, Cursor or VS Code. Nothing else: the hosted server needs no install.

What each role can do through the MCP

Role	Through the MCP
team	Search and read the whole library, read and export design systems, read the boards you own or that are shared with you, and add items to boards you own.
admin	The same, plus two curator filters on the browse tools: archived sites, and captures by completeness.
client	Nothing useful. A client sees the boards shared with them in the browser. The library tools need permission to read the library, and the board tools use routes a client is refused, so the library does not show a client the key icon that makes tokens.

What a token can and cannot do

An API token is you, for a process with no browser. Your client sends it to the hosted server as Authorization: Bearer … on every request, and the library treats it as it treats you signed in:

• It carries your role and nothing more. There are no narrower scopes: what your role can read, the token can read.
• What it does is attributed to you. A board item added through the MCP records your email as the person who added it.
• It cannot sign you in to the website, make another token, or invite anyone or change a role. Tokens are made only from a signed-in browser.
• The server writes in one place only: save_to_board adds items to a board you own. No tool deletes, reorders, renames, shares or archives anything.

Get an API token

1. Sign in and open the library.
2. Select the key icon in the top bar, beside Sign out. The API tokens for MCP dialog opens. The MCP guide link beside the key brings you back to this page.
3. Under New token, give it a label that says where it will live, such as claude-code-laptop or cursor-studio. The label is how you will know which token to revoke; up to 64 characters.
4. Choose its expiry. A dated token lasts 30, 60 or 90 days and then stops working on its own. Where the library offers Never expires, that is the default. A token that never expires works for as long as your account keeps its access: until you revoke it, or until an admin changes your role or removes your access, which revokes it for you.
5. Select Create. The token appears under Your new token — copy it now. Under Connect a client are the Claude Code command and the Cursor, VS Code and generic configs from Connect your client, token filled in, each with Copy.

Revoke a token

The same dialog lists every token on your account under Your tokens, with its label and when it expires, expired or was revoked. Select Revoke beside a live one. It stops working within a minute: the API refreshes its list of revoked tokens at most once a minute.

An account may hold 20 live tokens at a time. If an admin changes your role or removes your access, every token you hold is revoked with it, so make new ones after a role change.

Connect your client

The server is hosted at https://designstream.dev/mcp. Your client connects over Streamable HTTP and sends your token in an Authorization header. There is nothing to install, and the server is always the current release. The API tokens dialog shows each setup below with your token filled in.

Claude Code

claude mcp add --transport http -s user design-stream-library \
  https://designstream.dev/mcp \
  --header "Authorization: Bearer <your API token>"

• -s user makes the server available in every project on this machine.
• --header goes after the server name and the URL. The option takes several values, so placed first it would swallow them.
• claude mcp add refuses a name that already exists. To replace an entry — for a new token, say — remove it first, then add it again. The dialog's command does both in one line.

claude mcp remove -s user design-stream-library

Slash commands in Claude Code

Once connected, every client already has the Design Stream slash commands as prompts, with nothing to install; Claude Code lists them as /mcp__design-stream-library__ds-find and so on. To type the short names — /ds-find, /ds-site, /ds-tokens and the rest — in every project, with everything after the command passed along, put the command files in ~/.claude/commands:

mkdir -p ~/.claude/commands && curl -fsSL \
  -H "Authorization: Bearer <your API token>" \
  https://designstream.dev/api/mcp/claude-commands.tar.gz \
  | tar -xz -C ~/.claude/commands

• It writes ten files, ds-blend.md to ds-tokens.md, and replaces older copies of them; nothing else in the folder changes. Run it again to update them, and delete the files to remove the commands.
• The token is only used to download them and is not written into any file. The API tokens dialog shows this line with your token filled in.

Cursor

Cursor reads MCP servers from ~/.cursor/mcp.json for every project, or from .cursor/mcp.json inside one. Use the file in your home folder: a project's file is easy to commit, and this one holds your token. If it already lists servers, add the entry inside its mcpServers:

{
  "mcpServers": {
    "design-stream-library": {
      "url": "https://designstream.dev/mcp",
      "headers": {
        "Authorization": "Bearer <your API token>"
      }
    }
  }
}

Then open Cursor's MCP settings and check that design-stream-library is enabled.

VS Code

VS Code reads a workspace's MCP servers from .vscode/mcp.json, where the entry goes under servers and needs "type": "http". That file sits in a project, so keep it out of git — or run MCP: Open User Configuration from the Command Palette and put the same entry there, for every workspace:

{
  "servers": {
    "design-stream-library": {
      "type": "http",
      "url": "https://designstream.dev/mcp",
      "headers": {
        "Authorization": "Bearer <your API token>"
      }
    }
  }
}

Any other MCP client

Setting	Value
Transport	Streamable HTTP
URL	https://designstream.dev/mcp
Header	Authorization: Bearer <your API token>

A client configured by JSON usually takes some form of:

{
  "url": "https://designstream.dev/mcp",
  "headers": {
    "Authorization": "Bearer <your API token>"
  }
}

A client that cannot send a header with its requests, or that only starts servers on your own machine over stdio, cannot connect.

Claude Desktop and claude.ai

Claude Desktop and claude.ai custom connectors sign in with OAuth, which the hosted server does not offer yet, so neither can connect today. Until it does, use Claude Code, Cursor, VS Code or another client that sends a header.

Check the connection

In Claude Code, claude mcp list should show design-stream-library as connected, and /mcp inside a session shows its status and tools. In any client, start a new conversation and ask:

Call whoami and library_status from design-stream-library and tell me what they say.

whoami should name you. Trimmed, a good answer looks like this:

{
  "backend": "remote",
  "email": "you@example.com",
  "role": "team",
  "is_machine": false,
  "can": {"read": true, "boards": true, "shared_read": true,
          "curate": false, "operate": false, "users": false},
  "token": {"kind": "jwt", "exp": "2026-12-12T09:30:00Z"}
}

• can is what you may do. A false there is a refusal waiting to happen.
• token.exp is when this token stops working. A token that never expires has no exp.
• is_machine: true means the header does not carry your personal token, so nothing the assistant writes is attributed to you. Put your own token from the API tokens dialog in your client's header.

library_status should report "backend": "remote", "api": "https://designstream.dev", "token": true and "ok": true, with the library's counts and its search_mode. If ok is false, see Troubleshooting.

Tool reference

The server registers 22 tools, 14 prompts and a resource of standing instructions. Only save_to_board, marked writes, changes anything.

What every tool has in common

• The envelope. Every response carries backend, which on the hosted server is always remote: the answer came from the library's API. A failure is an answer, not a crash: {"error": {"code": …, "message": …}}, with http_status added when the API refused.
• Facets — page_type, industry, visual_style, category, color_mode, kind and tag — are exact-match filters. Each takes one value, a list, or a comma-separated string, up to 12 values. Values within a facet are OR; different facets are AND. The vocabulary is closed and case-sensitive: "Fintech" matches, and "fintech" quietly matches nothing. library_facets lists the real values.
• kind is a section kind: hero, nav, logos, testimonials, pricing, faq, cta, content, slide or footer. features and stats are accepted, but no section carries either.
• Paging. limit is held to 1–100. When a response has a next_cursor, pass it back as cursor for the next page; null means there are no more.
• Names. A site is named by its slug (stripe-com); its id is site-stripe-com. A section id looks like site-stripe-com#s03, and search and browse results return them.

Search and browse

Tool	Parameters	Returns
search_library	query, required: free text, best as a user story or a description — "a visitor comparing plans before upgrading" the seven facets limit, default 12; cursor	Page sections ranked against the query: mode, count, items (section id, kind, label, caption, user story, image URL, score and a short site summary) and next_cursor. The place to start. Archived sites are never searched.
browse_sites	q, optional: free text over name, title, h1, meta description and tags the seven facets, where kind means the site has a section of that kind include_archived, status: admin only limit, default 24; cursor	One row per site: slug, name, URL, page type, industry, category, colour mode, visual styles, tags, section count, capture date, section kinds with counts, and thumbnail URL. Newest capture first, or by relevance when q is given.
browse_sections	kind: the section is this kind q, and the other six facets, which filter on the section's site include_archived, status: admin only limit, default 48; cursor	Sections across every site, in the same shape as search_library, newest capture first when there is no q — "every pricing section we have". Lower the limit: 48 sections is a lot of context.
get_site	slug, required include_sections, default true include_design_system, default false include_headlines, default false	One site in full: metadata and image URLs; seo — meta tags, social cards, hero copy, JSON-LD types and on-page findings (null means the capture predates that pass, not that the page has no tags); the sections in page order; and, when asked, the design system (fonts, colour roles, spacing, radii, shadows, breakpoints and the site's own CSS variables) and the h1–h6 outline.
library_facets	include_archived, status: admin only	total_sites, and every value each facet actually holds with its count — for kind, a section count and a site count. Call it before filtering.

The admin-only filters: include_archived also lists sites an admin has archived, and status ("complete" or "incomplete") filters on whether the capture fully succeeded. For anyone else the API ignores both, and the response's scope says what was applied.

Design briefs, tokens and blocks

Tool	Parameters	Returns
get_design_brief	slug, required	The site as a Markdown design brief: colour roles as a table, the type ramp per family with the webfont that loaded, spacing and radii, the site's :root variables as CSS, the page's own copy, every section in order, and where the capture came from. Returns slug and markdown, about 1,600 tokens. Give it to the model when you are about to build in that site's style.
export_tokens	slug: a captured site, or design_system: a system you hold, such as a blend — give exactly one of the two format: json (default), css, tailwind or shadcn	The measured design system, shaped for a file. Returns content, size_bytes, unmapped (what the record could not supply; nothing is guessed to fill a gap) and notes (every value derived rather than read). See Export tokens for what each format contains.
compare_design_systems	slugs, required: 2 to 6 site slugs	The systems side by side, aligned row by row: colour roles by role and rank, the main font per usage, the type ramp, spacing and radii by step, colour mode and base unit. differences lists where they disagree most, with each site's value and a 0–1 spread. Nothing is averaged or recommended.
list_blocks	section_kind, such as "faq" library: "shadcn/ui", "aceternity" or "radix"	Open-source blocks from shadcn/ui, Aceternity and Radix, filed under the library's section kinds, each with its install command, the content it takes and which token roles it reads. When a kind has no block (pricing, logos and footer have none) a note says so. Filter it: the whole list is about 5,000 tokens.

Views

Each render_* tool takes one slug. In a client that supports MCP Apps, the extension that lets a tool return an interface, the result opens as an interactive panel in the conversation; every other client gets the same values as text. The two exports, marked admin · team, are refused to a client account with export_forbidden.

Tool	Parameters	Shows
render_style_board	slug	The colour roles as swatches with hex and token name, click to copy; a light/dark toggle when the capture recorded both; the type families with their webfont and fallback stack; and the radii.
render_type_scale	slug	Each font family's observed sizes, set at size with px and rem, and a copy-as-CSS export.
render_spacing_scale	slug	The spacing stops drawn to scale, whether each sits on the base-unit grid, and a copy-as-Tailwind export.
render_seo_board	slug	What the page says about itself: the hero copy, the h1–h6 outline in document order, the social card as a share preview, the meta tags with their lengths, the JSON-LD types and the on-page findings.
render_design_mdadmin · team	slug	The design brief laid out for a person to read, with Copy and Download. A brief longer than 16,000 characters is cut, and says so.
render_cssadmin · team	slug	The design tokens in all four export formats — CSS variables, Tailwind, shadcn and JSON — with a format switcher, Copy and Download. Each format is cut at 8,000 characters, and says so.
render_dna	slug	All of the above in one tabbed view: Style, Scales, SEO and Export. A client account gets no Export tab.

Boards

A board is a named set of sites and sections with a brief — the shortlist you share with a client.

Tool	Parameters	Returns
list_boards	include_archived, default false	The boards you own and the ones shared with you, a row each: id, name, item count, visibility (private, people or link), your access (owner, editor or viewer), when it was updated, and the owner's email for someone else's. How "the Acme shortlist" becomes a board id.
get_board	board_id, required limit, default 50; cursor	The board's brief (description) and owner; who else can see it, in one sentence; how you reach it (viewer.via, can_edit); and its items in order, each with its note, who added it and a short site or section reference. missing: true marks an item whose site has left the library, and a note that starts [agent] was written through the MCP.
get_board_brief	board_id, required max_sites, default 6, at most 12	The design brief of every site on the board as one Markdown document, under the board's name and brief. At about 1,600 tokens a site it keeps the first max_sites in board order, and names the rest in sites_omitted and in a closing line. Returns sites_included, sites_omitted, approx_tokens and markdown. Refused to a client account.
save_to_boardwrites	board_id, required items, required: up to 50 site slugs, site ids, section ids, or {"ref": …, "note": …} note: the note for every item without its own allow_shared, default false	Adds the items, in order, to a board you own, each with a note saying why it belongs; every note is saved as [agent] …. Returns count added and a result per item: added, or why not.

save_to_board refuses, before it writes anything:

• a board you do not own, including one shared with you as an editor (not_owner);
• a board already shared by link or with people, unless allow_shared is true, because what lands there is visible to them at once (board_is_shared) — an assistant should pass it only after you have agreed;
• an item with no note when no default note is given (note_required), and more than 50 items (too_many_items).

It never removes, reorders or overwrites: an item already on the board is reported and left as it is, note and all.

Identity and status

Tool	Parameters	Returns
whoami	none	Who the token belongs to: email, role, sub, is_machine, can (read, boards, shared_read, curate, operate, users) and token (its kind, and exp when it has one). Never the token itself.
library_status	none	Whether the library is answering: backend, configured_backend, api, library_dir, token, ok, search_mode, counts, env and health. On the hosted server both backends are remote, api is the address you connected to, token is always true, library_dir is null and env is empty. Call it when results look wrong or empty.

Prompts and standing instructions

The server also offers prompts: ready-made instructions for multi-step jobs that your client can insert into a conversation (in Claude Code, they appear as slash commands beginning /mcp__). Every argument is a string.

Prompt	Arguments	What it does
recommend_benchmarks	brief count, default "5"	Turns a design brief into a shortlist of benchmark sites, each with why it fits this brief, what to take from it (with values), what not to copy, and which sections to look at.
blend_design_system	slugs: comma-separated, or "board:<board_id>"	Builds one design system from several sites, each decision with its source, in the shape export_tokens accepts.
scaffold_with_blocks	source: a site slug, or "blend" blocks: comma-separated ids from list_blocks	Assembles a page from open-source blocks and themes them with a site's or a blend's tokens, without editing the blocks' markup.
template_for_story	user_story	Recommends the one presentation layout that suits what the reader is trying to do, with its reason and the data calls it needs.

Ten more are the Design Stream slash commands, named as you type them. Each takes one optional argument, arguments: whatever you would type after the command, as one string. Claude Code runs them as /mcp__design-stream-library__ds-find and so on, and hands a prompt only the first word typed after it; the prompt tells the assistant to take the rest from your message. To type /ds-find itself, with the whole line passed along, install the commands.

Prompt	What to type after it	What it does
ds-find	<brief, or a user story> [--kind hero|pricing|faq|…] [--count N]	Find benchmark sites or sections in the library for a brief, with the reasoning for each.
ds-site	<slug> [--brief] [--dna] [--sections] [--headlines]	Everything the library holds on one captured site — record, brief, or the visual DNA.
ds-compare	<slug> <slug> [slug …]	Put 2–6 sites' design systems side by side, with the places they disagree.
ds-blend	<slug> <slug> [slug …] | board:<id>	Synthesise one design system from several captured sites, then export it.
ds-tokens	<slug> [--format css|tailwind|shadcn|json]	Export a site's measured design system as CSS variables, a Tailwind theme, shadcn variables, or JSON.
ds-scaffold	<slug or "blend"> [--blocks id,id] [--kind hero|pricing|…]	Build UI from open-source blocks styled with a captured site's tokens.
ds-board	[board id] [--brief] [--archived]	List, read or export the boards this identity can see.
ds-save	<board id> <slug|section id> [slug …] --note "why"	Save sites or sections to a board you own, each with the reason it belongs there.
ds-brief	<slug>	Build a client-facing design brief for one site and export it as a single file.
ds-status	none	Who the Design Stream MCP thinks you are, which backend is serving, and what you may do.

The resource design-stream://instructions holds the standing rules for an assistant using this server: the closed facet vocabulary, how to treat lexical results, what each call costs in context, and how to write. If your client lets you attach a resource, attach it once per conversation.

Workflows

You do not call the tools yourself: you ask, and the assistant chooses them. Each workflow is a request you might make and the calls a good answer makes. Naming Design Stream in the request helps the assistant reach for this server.

Find references for a pricing page

Using Design Stream, find five pricing sections from SaaS or developer-tools sites that let visitors switch between monthly and annual billing. Dark mode if possible. Show me each one and say what it does well.

library_facets()
search_library(query="pricing tiers with a monthly and annual billing toggle",
               kind="pricing", industry="SaaS, Developer Tools", color_mode="dark", limit=8)
get_site(slug="…", include_sections=false)    # for the ones worth a closer look

library_facets comes first because a facet value outside the vocabulary matches nothing. Then read mode: when it is lexical, two or three short queries in the words a caption would use do better than one long sentence. For a shortlist with a written rationale per site, the recommend_benchmarks prompt runs this sequence for you.

Build in a site's style

Get the Design Stream design brief for stripe-com, then build our pricing page in that style — its palette, type ramp, spacing and radii. We use Tailwind.

get_design_brief(slug="stripe-com")
export_tokens(slug="stripe-com", format="tailwind")

The brief is the context: measured values the model can rely on as fact about the page on its capture date. The export is the file: its content goes into your Tailwind config, and unmapped lists anything the capture could not supply. In the library, a site's Design system panel shows the exact get_design_brief call for that site, ready to copy.

Compare two design systems

Compare the design systems of linear-app and vercel-com in Design Stream. Where do they differ most? Then blend them into one system for a developer-tools landing page and export it as CSS variables.

compare_design_systems(slugs=["linear-app", "vercel-com"])
# the blend: the model's own, or the blend_design_system prompt's
export_tokens(design_system={…}, format="css", slug="linear-vercel-blend")

differences says where the two disagree and by how much; the tool never picks a winner. The blend is the model's work — the blend_design_system prompt makes it name a source for every decision — and export_tokens with an inline design_system turns it into a file without fetching anything. With design_system, slug only labels the output.

Export tokens

Export notion-so's design tokens from Design Stream as a shadcn globals.css block and add it to app/globals.css.

export_tokens(slug="notion-so", format="shadcn")

Format	What content holds
json	The design system, normalized: colour roles ranked by how much they are used, fonts with their stacks and the webfont that loaded, the type ramp, spacing, radii, shadows, breakpoints and the site's own :root variables.
css	A :root block of --ds-color-*, --ds-font-*, --ds-text-*, --ds-space-*, --ds-radius-*, --ds-shadow-* and --ds-breakpoint-* properties, then the site's own :root variables, untouched.
tailwind	theme_extend, an object for tailwind.config.js (colors.ds, fontFamily, fontSize, spacing, borderRadius, boxShadow), and js, the same object as source to paste.
shadcn	The globals.css variables shadcn/ui components read — --background, --foreground, --primary, --secondary, --muted, --accent, their foregrounds and --radius — mapped from the colour roles, in a .dark block when the capture is dark.

Check unmapped and notes before you paste. To look first, render_css shows all four formats side by side.

Curate a board and hand it to an agent

Find three hero sections for a calm, editorial fintech landing page and save them to my “Acme — homepage” board in Design Stream, with a sentence on why for each.

whoami()
list_boards()
search_library(query="calm editorial hero with a product screenshot",
               kind="hero", industry="Fintech")
save_to_board(board_id="…", items=[
    {"ref": "site-…#s01", "note": "Quiet serif headline over a single product shot."},
    …
])

The assistant should check whoami first and tell you what it is about to write. It can add only to a board you own. If that board is already shared, the tool refuses until the assistant passes allow_shared, which it should do only once you have said so, because the notes appear to the people it is shared with straight away. Every note is saved with an [agent] prefix, so readers can tell it from yours.

Later — in another client, or a colleague's with access to the board — hand the whole board over as context:

Read the Design Stream board brief for board 3f6c9a1e-…, then propose one design system for the Acme homepage from those sites.

get_board(board_id="3f6c9a1e-…")    # what is on it, and the owner's brief
get_board_brief(board_id="3f6c9a1e-…", max_sites=6)

A board's page in the library shows its get_board_brief call with the id filled in, ready to copy. The brief keeps the first max_sites sites, at most 12, and names the ones it left out, so an assistant never mistakes a cut document for the whole board.

Search modes

Read mode

Every search_library response says how its results were ranked:

Mode	Meaning
hybrid	Embeddings and full-text search together. Results are ranked by meaning, so a query written as a user story works.
lexical	Word overlap only, because semantic search was not available. The top hit shares the most words with your query; it is not the best design. The response carries a note saying so. Short queries in the words a caption would use work better.
facet_only	The query was empty, so this is a filtered list, newest first: an enumeration, not a ranking.

library_status reports the search_mode the library can offer.

Where answers come from

The hosted server answers every call from the library's API, with your token. That is what "backend": "remote" in each response means; it never falls back to anything else, so a refusal or an outage is an error you can see rather than a quietly different answer.

Troubleshooting

Start with library_status and whoami: whether the library is answering, and who the server thinks you are, answer most of the questions below.

The hosted server fails to connect, or answers 401

The server refuses a connection whose Authorization header is missing, mistyped, expired or revoked, before any tool runs, so the client shows the server as failed rather than returning an error from a tool. Check the header reads Bearer, one space, then the whole token, and check the token's status in the API tokens dialog. If it is gone, make a new one and replace the entry. A token revoked while your client is connected is refused the same way, within a minute.

library_status says "ok": false

The library's API did not pass its own health check, and health holds what it answered. This is not your token or your setup: a token the server refuses never reaches a tool. Try again in a few minutes, and if it lasts, tell the person who invited you.

Calls fail with forbidden (403)

Your role may not do that, and the message names the roles that may. A client account cannot use the library tools, so ask for a team account if you need them.

No results, or fewer than expected

• A facet value is not in the vocabulary. Values are exact and case-sensitive, and an unknown one matches nothing without an error. Ask for library_facets and use its values.
• kind is features or stats. No section carries either; search by text instead.
• mode is lexical. A long, sentence-like query shares few words with any caption. Try shorter queries.
• The site is archived. Search never includes archived sites, and only an admin can list them.

claude mcp add says the server already exists

Run claude mcp remove -s user design-stream-library, then the add command again. The command the API tokens dialog gives you does both.

Security

• Whoever can read the config file holds the token. Claude Code keeps user-level servers, with their headers, in ~/.claude.json; Cursor and VS Code keep them in the files under Connect your client. Anyone, or any program, that can read that file can use the library as you — everything your role can read, and your boards — until the token expires, you revoke it, or your role or access changes.
• Keep it out of repositories. Never put a token in configuration that gets committed, such as the .mcp.json that claude mcp add -s project writes, a project's .cursor/mcp.json, or a .vscode/mcp.json that is not ignored. Use the user-level setups on this page.
• One token per machine and client, labelled for where it lives, so a lost laptop means revoking one token and nothing else.
• Revoke what you do not recognise. A token that never expires works for as long as your account keeps its access, so look through Your tokens now and then. Revoking takes effect within a minute.
• Never paste a token into a conversation. Your client sends it in a header. The assistant never needs to see it, and whoami and library_status report only whether one is set and what kind it is.
• What the assistant writes is yours. save_to_board records you as the person who added each item, and anyone the board is shared with can read its notes. Read what your assistant proposes to save.

If a token has leaked, revoke it in the API tokens dialog, make a new one, and replace the old one in your client's configuration.