How to connect Brandfetch MCP with TypeScript

Search for brands by name using Brandfetch's search index. Use this when you do NOT already know the brand's domain — for example, when the user gives a brand name with ambiguous or unknown domain ("Madame Kim", "the raclette brand", "starbuks"), or a name that could map to multiple companies ("Delta" — airline? faucets? dental?). For raw bank or card transaction strings, use enrich_transaction instead. Returns a ranked list of matches. Each match contains: - `brandId` (str): Brandfetch's internal ID. - `domain` (str): The brand's primary domain. Pass this to `get_brand` (one brand, interactive card), `get_brand_data` (one brand's data for a task) or `get_brands` (several brands in one call) to fetch its details. - `name` (str): Display name. - `icon` (str): CDN URL to a small representation of the brand, suitable for autocomplete-style UIs. Display-only: embed it as returned (e.g. in an `<img>` tag) — it is not programmatically fetchable, and must not be edited. For other asset types, sizes, or downloadable bytes, call `get_brand` or `get_brand_data`; for display-only variants, `build_logo_urls`. - `claimed` (bool): Whether the brand has officially claimed their listing. Claimed brands generally have higher-quality, brand-approved assets. - `verified` (bool): Whether Brandfetch has verified the listing. - `qualityScore` (float, 0–1): Completeness of the brand data. - `_score` (float): Search relevance for this query; higher = better match. Use to rank results; not comparable across different queries. Results are already sorted by relevance; the first result is usually the best match for well-known brands. When the user's goal is to see the brand or grab its assets, follow up with get_brand on the chosen domain — on MCP Apps hosts it renders an interactive card with logo preview, download, and copy-URL actions. When several results feed one deliverable (a logo wall, a table, a slide), follow up with one get_brands call for all of them instead — no card.

Show a brand to the user. Looks up full brand data by domain, website URL, email address, stock ticker, ISIN, or crypto symbol and, on MCP Apps hosts (claude.ai, Claude Desktop), renders it as an interactive brand profile card in the conversation: live logo preview with variant/format switchers and one-click Download / Copy URL, plus tabs for colors, fonts, images, company facts and brand voice. Use this when the user wants to SEE, view, explore or pick from ONE brand inside the conversation: - "show me Nike's logo", "what does their branding look like", "Okta's brand voice", - download a logo file, or copy a URL / embed link they can use directly, - compare variants (logo vs symbol vs icon, light vs dark) or formats (SVG, PNG, WebP) and pick one. When the user names an aspect (colors, fonts, imagery, company info, brand voice), set `view` so the card opens on that tab. Once the card is rendered, don't re-list asset URLs in text — its Download and Copy URL buttons already hand the user the exact file and a ready-to-use URL. Use `get_brand_data` instead — same lookup, same response, no card — when the brand data is an INPUT to something you are producing rather than the thing the user wants to look at: content, code or documents generated from the data, or background on what a company does. For several brands assembled into a logo wall, table, slide or comparison, use `get_brands`: one call for all of them. Never call this tool once per brand for a multi-brand request: each call renders its own card. Call this directly when you have a confident identifier — either from a prior `brand_search` result, or from your own knowledge for well-known brands (e.g. "coca-cola.com" needs no search first). If the identifier is uncertain or the brand is obscure, use `brand_search` first to disambiguate. The identifier is auto-resolved in this order: domain → ticker → ISIN → crypto. Examples (all Nike): "nike.com", "NKE", "US6541061031". For crypto: "BTC", "ETH". An identifier that contains "@" is read as an email address and resolved to the brand behind its registrable domain: an address at nike.com gives Nike. Mailbox-provider domains resolve like any other domain. You judge whether the domain is the contact's company — the API does not. A website URL is read as the brand behind its host ("https://www.nike.com/en/help" → Nike, and "nike.com/en/help" without a scheme too): scheme, "www.", path and query all fall away, so pass the URL you have rather than trimming it yourself. For clean brand name lookups, prefer brand_search followed by this tool — those are more reliable for unambiguous queries. Set `view` to the aspect of the brand the user asked about, and the interactive card opens on that tab: "okta brand voice" → "brand_voice", "brandfetch colors" → "colors", "their fonts" → "fonts". Omit it for general lookups. It never changes the returned data, and hosts without the card simply ignore it. Returns a brand object containing: - `name`, `domain`, `description`: Core identity. - `logos` (list): Typed visual assets. The `type` field distinguishes: * `logo`: The full brand mark, typically a wordmark or wordmark+symbol combination intended for headers, signatures, and contexts with horizontal space (e.g. "Coca-Cola" in script). * `symbol`: The standalone graphical mark without text, used when the brand is already identified by context (e.g. the Nike swoosh alone). * `icon`: A square, compact representation optimized for small sizes — favicons, app icons, avatars, list items. May be the symbol, an initial, or a simplified mark. * `other`: Anything that doesn't fit the above (mascots, seals, etc.). Pick by use case, not by name: a "show me the logo" request from a user usually wants `type: "logo"` for display, but `type: "icon"` for a small UI element like a list row or chat avatar. - `colors` (list): Brand colors as `{hex, type, brightness}` where `type` is `primary` | `accent` | `dark` | `light` | `brand`. - `fonts` (list): `{name, type, origin, originId}`. - `links` (list): Social and web links as `{name, url}`. - `company`: Metadata including `industries`, `employees`, `foundedYear`, `location`, and `kind` (public | private | etc.). **IMPORTANT — use all URLs exactly as returned:** Every URL in the response (logo `src` fields, image URLs, etc.) must be used verbatim. Do not modify, rewrite, or substitute any part of them — including the `?c=` query parameter. That token is a per-request credential issued by the API specifically for this response; replacing it with any other client ID (including one from context or memory) will break the URL. To download asset bytes, fetch the `src` URL directly (curl/requests) whenever your environment can reach cdn.brandfetch.io — that keeps the bytes out of the conversation. On claude.ai a blocked fetch means `*.brandfetch.io` is missing from the code-execution network allowlist (Settings > Capabilities): tell the user to add it — or, on Team/Enterprise plans, to ask an Owner/Admin — before generating anything that embeds brand images; the experience is much better with it. Clients that support MCP resource reads can otherwise use the `resource_link` blocks this tool returns (`bf://asset/{domain}/{type}`). Errors: - 403 / "explicit deny": The brand exists in the index but the plan behind the API key has no API credits, or the key lacks access. Do not retry — fall back to displaying the `icon` URL from `brand_search` (display-only, not downloadable) and tell the user to check their plan. Account state, not a bug: never report it with send_feedback. - 404: Identifier not found. Try `brand_search` with a name query instead. - 429: API quota exhausted for the billing period. Do not retry — `brand_search` and `build_logo_urls` do not consume quota and keep working. Account state, not a bug: never report it with send_feedback. If the returned data is visibly wrong or stale (wrong logo, outdated colors, missing company info), report it with send_feedback (category "data-quality"), including the brand's domain.

Fetch a brand's data by domain, website URL, email address, stock ticker, ISIN, or crypto symbol — as data, with no interactive card. Same lookup, same response and same credentialed asset URLs as `get_brand`. Use this when the data FEEDS A TASK rather than a display: - several brands — logo walls, comparison tables, customer or partner slides, lists of companies: call `get_brands` once with all of them instead. Call this tool for a brand whose full record you need (`get_brands` returns a compact one), or once per brand (calls can run in parallel) when `get_brands` is refused for the plan, - generating content or code from brand data — HTML/CSS using the brand colors, a deck or document embedding the logo, design tokens, on-brand copy, - programmatic processing — fetching asset bytes from the `src` URLs, extracting a palette, reading a company's industry, size or founding year, - context for yourself — understanding what a company does before answering; pair with `get_brand_context` for voice, audience and positioning. If the user's goal is to SEE one brand — its logo, colors or profile in the conversation — or to download or copy an asset themselves, call `get_brand` instead: on claude.ai and Claude Desktop it renders an interactive card with preview, download and copy-URL actions, which beats pasting URLs into text. Call this directly when you have a confident identifier — either from a prior `brand_search` result, or from your own knowledge for well-known brands (e.g. "coca-cola.com" needs no search first). If the identifier is uncertain or the brand is obscure, use `brand_search` first to disambiguate. The identifier is auto-resolved in this order: domain → ticker → ISIN → crypto. Examples (all Nike): "nike.com", "NKE", "US6541061031". For crypto: "BTC", "ETH". An identifier that contains "@" is read as an email address and resolved to the brand behind its registrable domain: an address at nike.com gives Nike. Mailbox-provider domains resolve like any other domain. You judge whether the domain is the contact's company — the API does not. A website URL is read as the brand behind its host ("https://www.nike.com/en/help" → Nike, and "nike.com/en/help" without a scheme too): scheme, "www.", path and query all fall away, so pass the URL you have rather than trimming it yourself. For clean brand name lookups, prefer brand_search followed by this tool — those are more reliable for unambiguous queries. Returns a brand object containing: - `name`, `domain`, `description`: Core identity. - `logos` (list): Typed visual assets. The `type` field distinguishes: * `logo`: The full brand mark, typically a wordmark or wordmark+symbol combination intended for headers, signatures, and contexts with horizontal space (e.g. "Coca-Cola" in script). * `symbol`: The standalone graphical mark without text, used when the brand is already identified by context (e.g. the Nike swoosh alone). * `icon`: A square, compact representation optimized for small sizes — favicons, app icons, avatars, list items. May be the symbol, an initial, or a simplified mark. * `other`: Anything that doesn't fit the above (mascots, seals, etc.). Pick by use case, not by name: a "show me the logo" request from a user usually wants `type: "logo"` for display, but `type: "icon"` for a small UI element like a list row or chat avatar. - `colors` (list): Brand colors as `{hex, type, brightness}` where `type` is `primary` | `accent` | `dark` | `light` | `brand`. - `fonts` (list): `{name, type, origin, originId}`. - `links` (list): Social and web links as `{name, url}`. - `company`: Metadata including `industries`, `employees`, `foundedYear`, `location`, and `kind` (public | private | etc.). **IMPORTANT — use all URLs exactly as returned:** Every URL in the response (logo `src` fields, image URLs, etc.) must be used verbatim. Do not modify, rewrite, or substitute any part of them — including the `?c=` query parameter. That token is a per-request credential issued by the API specifically for this response; replacing it with any other client ID (including one from context or memory) will break the URL. To download asset bytes, fetch the `src` URL directly (curl/requests) whenever your environment can reach cdn.brandfetch.io — that keeps the bytes out of the conversation. On claude.ai a blocked fetch means `*.brandfetch.io` is missing from the code-execution network allowlist (Settings > Capabilities): tell the user to add it — or, on Team/Enterprise plans, to ask an Owner/Admin — before generating anything that embeds brand images; the experience is much better with it. Clients that support MCP resource reads can otherwise use the `resource_link` blocks this tool returns (`bf://asset/{domain}/{type}`). Errors: - 403 / "explicit deny": The brand exists in the index but the plan behind the API key has no API credits, or the key lacks access. Do not retry — fall back to displaying the `icon` URL from `brand_search` (display-only, not downloadable) and tell the user to check their plan. Account state, not a bug: never report it with send_feedback. - 404: Identifier not found. Try `brand_search` with a name query instead. - 429: API quota exhausted for the billing period. Do not retry — `brand_search` and `build_logo_urls` do not consume quota and keep working. Account state, not a bug: never report it with send_feedback. If the returned data is visibly wrong or stale (wrong logo, outdated colors, missing company info), report it with send_feedback (category "data-quality"), including the brand's domain.

Fetch several brands in one call: up to 25 identifiers, one compact record per brand, no interactive card. For a longer list, call it again with the rest; calls can run in parallel. Use this whenever a task involves two or more brands — a logo wall, a comparison table, customer or partner slides, a list of companies to enrich: one call with all of them, not one `get_brand_data` call per brand. Use `get_brand_data` for a single brand or for a brand's full record, and `get_brand` when the user wants to see one brand. Batch lookups need a paid plan or prepaid credits. On a free plan the call is refused and nothing is charged: fetch the brands with `get_brand_data` instead, one call per brand (calls can run in parallel). Each identifier is read the way `get_brand_data` reads one — a domain, a website URL on it, an email address at it, a stock ticker, an ISIN or a crypto symbol, auto-resolved in the order domain → ticker → ISIN → crypto. Set `identifier_type` when every identifier is of one kind: an exchange-suffixed ticker such as "BHP.AX" is otherwise read as a domain. For a name whose domain you are unsure of, use `brand_search` first. Returns JSON `{"results": [...]}` with one entry per identifier, in the order sent, each carrying the `identifier` and a `status`: - 200: `brand` is a compact record — `id`, `name`, `domain`, `claimed`, `description`; `logos`, the brand's `logo`, `symbol` and `icon` assets (types as in `get_brand_data`), each with its `theme` and `formats` (`format`, `src`, and `width`/`height` for raster files); `colors` (`hex`, `type`); `fonts` (`name`, `type`, `origin`); and `company` (`employees`, `foundedYear`, `kind`, `location`, `industries` by name). Banners and other images, social links, the long description and logos of type `other` are left out: call `get_brand_data` for a brand when the task needs them. - 202 (`code` "crawl_queued"): not indexed yet. Brandfetch has queued it for indexing, so ask for these again later; they are also listed in `askAgainLater`. To get one of them now, call `get_brand_data` with it, which crawls a new brand while it waits. - 400: not a valid identifier; `message` says why. - 404: no brand for this identifier. Try `brand_search` with the company's name. - 413, 500, 504: not answered this time; they are also listed in `retryNow`. Ask for them again — after a 413, in a smaller batch. Each brand returned (200) uses one API credit. Every other result is free, and an identifier repeated in one call — or the same domain spelled twice — is charged once. **IMPORTANT — use all URLs exactly as returned:** Every URL in the response (logo `src` fields, image URLs, etc.) must be used verbatim. Do not modify, rewrite, or substitute any part of them — including the `?c=` query parameter. That token is a per-request credential issued by the API specifically for this response; replacing it with any other client ID (including one from context or memory) will break the URL. To download asset bytes, fetch the `src` URL directly (curl/requests) whenever your environment can reach cdn.brandfetch.io — that keeps the bytes out of the conversation. On claude.ai a blocked fetch means `*.brandfetch.io` is missing from the code-execution network allowlist (Settings > Capabilities): tell the user to add it — or, on Team/Enterprise plans, to ask an Owner/Admin — before generating anything that embeds brand images; the experience is much better with it. Errors that refuse the whole call, with nothing charged: - 403 "paid plan required": use `get_brand_data` once per brand, as above. Account state, not a bug: never report it with send_feedback. - 429: fewer API credits remain than this call could use; the message says how many remain. Ask for at most that many brands, or tell the user to add credits. Account state, not a bug: never report it with send_feedback. - 403 (any other): the plan has no API credits, or the key lacks access. Do not retry; tell the user to check their plan. - 400: the request itself was malformed, e.g. an empty identifier; the message names it. If the returned data is visibly wrong or stale, report it with send_feedback (category "data-quality"), including the brand's domain.

Identify a merchant brand from a credit card or bank statement string. Uses AI-based matching to resolve abbreviated, truncated, or cryptic transaction labels (e.g. "SQ *COFFEE SHOP 4412", "AMZN MKTP US") to a brand. Use this when the input is a raw statement line rather than a clean brand name. Returns brand data matching the shape from `get_brand` (domain, name, logos, colors, etc.) for the identified merchant, or an error if no confident match is found. URLs in the response carry per-request credentials — use them exactly as returned, never edited (same rule as `get_brand`). Examples: - transaction_label: "STARBUCKS GENEVA", country_code: "CH" - transaction_label: "AMZN MKTP US", country_code: "US" - transaction_label: "IKEA", country_code: "CH" - transaction_label: "SQ *BLUE BOTTLE", country_code: "US" Errors: - 403: The plan behind the API key has no API credits, or the key lacks access. Do not retry; tell the user to check their plan. Account state, not a bug: never report it with send_feedback. - 429: API quota exhausted for the billing period. Do not retry — `brand_search` and `build_logo_urls` do not consume quota and keep working. Account state, not a bug: never report it with send_feedback.

Get LLM-ready brand context for a known domain — voice, audience, positioning, style. This is the *subjective* counterpart to `get_brand` / `get_brand_data` (same data; the first renders an interactive card, the second returns plain data). Use them together by what kind of data you need: - `get_brand` / `get_brand_data` → objective, structured facts: logos, colors, fonts, links, industry, employee count, founding year. Use when rendering UI, building a profile card, or citing firmographics — `get_brand_data` when the facts feed content you are generating. - `get_brand_context` (this tool) → probabilistic, interpretive data: how the brand sounds, who it talks to, what it values, what it sells, how it feels visually. Use when generating content, reasoning about fit, or grounding an LLM in a brand's identity. Both take the same domain and can be called in parallel when you need both. USE THIS WHEN: writing copy in a brand's voice, generating on-brand product descriptions, classifying whether content fits a brand, summarizing a company for a pitch, picking a target audience for a campaign, or describing a brand's aesthetic in words. For obscure or ambiguous brand names, run `brand_search` first to resolve the canonical domain, then call this with the result. Returns JSON with: - `meta.domain`, `meta.canonical_name`, `meta.resolved_at`: the resolved brand and when the context was generated. If `canonical_name` differs from what the user said (e.g. user said "MS", canonical is "Microsoft"), surface that. - `identity.tagline`, `identity.mission`: the brand's own words — quote verbatim, do not paraphrase. - `identity.description`: a neutral 1–2 sentence summary, safe to paraphrase. - `identity.tags`: short category labels for routing or classification. - `positioning.value_proposition`: use as headline framing in marketing or pitch contexts. - `positioning.target_audience[]`: distinct segments, each with its own description. Pick the segment that matches the user's task — do not blend them into a generic "everyone." - `positioning.products_and_services[]`: each entry has `name`, `type` ("product" | "service"), and `description`. Use to ground specific claims and avoid hallucinating offerings the brand doesn't have. Entries may also carry `category`, `features[]` (what a customer can do with the offering, each starting with a verb: "Manage inventory"), `tags[]`, `url` (the offering's page) and `pricing` (`model`, `free_tier`, `starting_price` with `currency` and `unit`, `plans[]`, `url`). These are null (the lists may instead be empty) when the brand's site doesn't state them: never fill a null `pricing` with an estimate. - `brand.voice.summary`: prose description of the brand's tone, suitable as a system-prompt preamble when generating copy. - `brand.voice.attributes`: positive descriptors (e.g. "warm", "witty"). - `brand.voice.avoid`: anti-patterns. Treat as hard constraints when generating copy, not soft preferences — if the list says "avoid hype", do not write hype. - `brand.style`: visual/design vibe in words (e.g. "clean, dense, utilitarian"). Useful for image-generation prompts or describing the brand's aesthetic. For actual color codes, fonts, or logo files, call `get_brand` instead. - `competition.competitors[]`: up to five named competitors, most direct first, each with `name`, `domain`, `type` ("direct" | "indirect"), `category`, `positioning` and `overlap[]` (why it competes). An empty list means none could be identified, which is normal for small local businesses; `competition: null` means the context predates the field. Pass a competitor's `domain` to `get_brand` for its logo and colors. Note that this is generated content — language may occasionally be flowery or non-English. Treat it as a strong starting point, not gospel. If the context is clearly wrong for the brand (wrong company, hallucinated products, non-English output), report it with send_feedback (category "data-quality"), including the domain. A domain seen for the first time is generated on the spot, which can take up to a minute. This tool waits for it; if the context is still being generated when it stops waiting, the error says so: call this tool again in about 30 seconds, by when it should be ready. Errors: - Still being generated: call again in about 30 seconds (see above). - 503: Service temporarily unavailable. Retry once after a brief delay. If it persists, fall back to `get_brand` for the objective subset and tell the user that subjective brand context is currently unavailable. - 422: The brand's site blocks automated access, so no context can be generated for it. Do not retry; use `get_brand` for the objective subset. - 404: No context could be generated for this domain. Try `brand_search` to find a canonical domain, then retry. - 403: Authentication, access tier, or no-credits plan. Do not retry; tell the user to check their plan. Account state, not a bug: never report it with send_feedback. - 429: API quota exhausted for the billing period. Do not retry — `brand_search` and `build_logo_urls` do not consume quota and keep working. Account state, not a bug: never report it with send_feedback.

Construct Brandfetch Logo CDN URLs for one or more brands. No API call is made — returns ready-to-embed URL strings. **HOTLINKING POLICY — read before using these URLs:** URLs returned by this tool are subject to Brandfetch's hotlinking policy. They are intended for direct browser rendering only (e.g. `<img src="...">` in an HTML page). Programmatic fetching or downloading of these assets — such as HTTP GET requests from a server or script using only the clientId embedded in the URL — will be blocked and return an error. If the session has no clientId at all, the URLs are built without a `?c=` token and the result is `{"urls": [...], "warning": "..."}` instead of a plain list — those URLs cannot be fetched programmatically under any circumstances. If you need to actually download or process an asset (save to disk, read pixel data, attach to an email, etc.), use `get_brand_data` (or `get_brand`, or `get_brands` for several brands) instead. The CDN URLs embedded in their responses carry per-request credentials that allow programmatic access. Use this tool when you want to: - Embed brand logos directly in a web page or UI component - Provide a displayable image URL to the user - Understand the URL grammar to tune dimensions, theme, or asset type for logos already obtained via `get_brand` or `get_brand_data` When the user wants to preview, compare, or download a brand's assets themselves, prefer `get_brand` — on MCP Apps hosts it renders an interactive card (preview, download, copy-URL), and its URLs carry per-request credentials that allow programmatic fetching. Accepts multiple identifiers in a single call to avoid repeated round trips. All identifiers share the same display options (type, theme, dimensions, fallback). The returned list is in the same order as the input.

Send feedback about the Brandfetch MCP server to the Brandfetch team. Use this to report anything that would help improve this MCP server: - A tool call failed, timed out, or returned something inconsistent with its documented behavior. - A tool description was confusing or misled you into a wrong call. - Brand data was wrong, stale, or missing (wrong logo, outdated colors, missing company info) — include the brand's domain in the message. - A capability you needed was missing (e.g. a filter, a data field, a whole tool). - The user explicitly asked to send feedback, or expressed praise or frustration about Brandfetch that they want passed along. Write feedback the way you would want to receive a bug report: what you were trying to do, the exact tool call and arguments, what you expected, and what actually happened. Specific and structured beats polite and vague. Send one call per distinct issue rather than bundling several topics into one message. Do NOT use this tool for credit, quota, or plan errors — a 401, a 403 "no API credits", or a 429 "quota exhausted". Those describe the user's account, not a defect: the Brandfetch team cannot act on them and such reports are filtered out before anyone reads them. Tell the user to check their plan and credits at https://developers.brandfetch.com instead. If a credit error surfaced alongside a genuine data or tool problem, report only the latter. This is a one-way channel to the Brandfetch team — nobody replies through it. For account or billing help, direct the user to https://developers.brandfetch.com instead. Never include API keys, bearer tokens, or personal data in the message. Returns a JSON acknowledgment: {"status": "received", ...}, or {"status": "declined", "reason": "account_state", ...} for credit / quota reports.