Developers / MCP Integration Guide

SKB exposes public reference content through web pages, discovery files, structured data, raw entity formats, and a read-only MCP server.

MCP endpoint

https://mcp.skinknowledgebase.com/mcp

The MCP server uses JSON-RPC over HTTP POST to /mcp via Streamable HTTP transport. It is currently public read-only and does not require authentication.

Tools

• search — generic retrieval search. Input: { "query": "blackheads", "limit": 10, "entity_type": "Question|Concern|Ingredient|Product|SideEffect|Source" } (the entity_type filter is optional; legacy type is also accepted). Response: { "results": [{ "id": "<canonical-url>", "entity_id": "<ULID>", "entity_type": "Question", "title": "...", "slug": "...", "url": "<canonical-url>", "canonical_url": "<canonical-url>", "snippet": "...", "matched_fields": ["title", "slug", "aliases"], "score": 0.94, "updated_at": "<ISO 8601>" }] }. Scores are normalized 0–1. The matched_fields array reports which fields contributed to the match (title, slug, aliases, quick_answer, quick_summary, body_heading, body_paragraph, related_entity, source_fact).
• fetch — generic retrieval fetch. Input: { "id": "<canonical-url-or-ULID>" }. Response: { "id": "...", "url": "...", "title": "...", "entity_type": "...", "text": "...", "structured": {...}, "evidence_sources": [...], "product_fact_sources": [...], "updated_at": "..." }. For Question entities, structured.search_aliases exposes the 8–15 authored consumer-phrasing variants for that page. Source roles are separated: evidence_sources cover peer-reviewed, medical-reference, regulatory, dermatology-institution, and clinical-guideline sources; product_fact_sources cover official-product-page, retailer-product-page, and manufacturer-clinical-data sources. Product and product-fact sources should not be cited as efficacy evidence.
• get_entity — fetch one entity by type and slug or id. Input: { "type": "Ingredient", "slug_or_id": "matrixyl" }. Response: { "entity": { ...canonical entity... } }.
• get_question_bundle — fetch a Question plus linked concerns, ingredients, products, and sources. Input: { "slug_or_id": "what-does-matrixyl-do-for-skin" }. Response: { "question": {...}, "ingredients": [], "concerns": [], "ranked_products": [{...}], "sources": [] }. The returned Question carries structured.search_aliases for AI-client search-quality debugging.
• get_ranked_products_for_question — fetch the Ranked Products for a Question, capped at 2. Input: { "slug_or_id": "question-slug" }. Response: { "ranked_products": [{...}] } or { "ranked_products": [] }.
• get_sources_for_question — fetch cited Source entities for a Question. Input: { "slug_or_id": "question-slug" }. Response: { "sources": [{...}] }.
• search_questions — search Question pages. Input: { "query": "puffy eyes" }. Response: { "results": [{ "title": "...", "slug": "...", "score": 1 }] }. Shares the same ranking engine as search (normalization, synonym expansion, FTS-fallback chain, alias matching).
• search_entities — search across entity types. Input: { "query": "caffeine", "entity_type": "Ingredient" } (legacy type is also accepted). Response: { "results": [{ "entity_type": "Ingredient", "slug": "caffeine" }] }.
• list_entities — list entities by type. Input: { "entity_type": "Source" }. Response: { "entities": [{ "title": "...", "slug": "..." }] }.

Search quality

The MCP search layer is designed to tolerate natural-language partial, reordered, and synonym queries from AI clients rather than requiring exact-title matches. The pipeline applies:

• Query normalization — lowercase, punctuation stripping, hyphen and apostrophe normalization, whitespace collapse, light singular/plural handling, stopword downweight (e.g., does, do, is, can, how, what, why, my, the, a, an, actually, really, best, good), and preservation of meaningful skincare tokens (e.g., c, spf, aha, bha, uv, uvb, uva, 2%, 10%).
• Field-weighted ranking — exact title and slug matches outrank token overlap, which outranks search aliases, which outrank Quick Answer or Quick Summary matches, which outrank body section heading or paragraph matches, which outrank related-entity or source matches.
• Synonym expansion — common consumer phrasings map to canonical terms (for example minimize, shrink, reduce appearance all map to pore-reduction queries; vitamin c, vit c, ascorbic acid, l-ascorbic acid map to the same Ingredient).
• Fallback chain — when a strict full-text query returns no rows or weak rows, the layer falls back through OR-style token matching, ILIKE on title and slug, trigram similarity, synonym-expanded query, and alias-only matching. Listed reference queries reliably surface their intended page in the top 1–3 results.
• Per-Question search aliases — every published Question carries 8–15 authored consumer-phrasing aliases (exact-title variant, shortened, reordered, synonym, casual consumer language, product-seeking, ingredient-seeking, and "worth it / does it work" framings where relevant). Aliases are exposed under structured.search_aliases in the fetch and get_question_bundle responses.

Alternate page formats

Every public entity page has raw alternates at the same URL pattern plus /raw.md or /raw.json, for example https://skinknowledgebase.com/questions/<slug>/raw.json.

Markdown alternates return text/markdown; charset=utf-8. JSON alternates return application/json; charset=utf-8. Entity HTML pages emit <link rel="alternate" type="text/markdown" ...> and <link rel="alternate" type="application/json" ...> tags for discovery. Raw alternates are also enumerated in the per-type sitemaps so crawlers can discover them without inspecting HTML heads.

Discovery files

Use /robots.txt, /sitemap.xml, /llms.txt, /llms-full.txt, and /feed.xml for crawl and ingestion workflows. Per-entity raw formats are discoverable from canonical HTML pages through their alternate links and from the per-type sitemap entries.

Rate limits and uptime

We do not currently rate-limit MCP queries. We may add per-IP soft caps if abuse appears. The service is monitored; if MCP is unavailable, fall back to crawling public web pages.

Structured data

Entity pages emit Schema.org JSON-LD from a single @graph. Types currently emitted include Article, FAQPage, Question, and Answer for Question pages; Article for Concerns and Side Effects; ChemicalSubstance for Ingredients when INCI data is present, otherwise Article; Product for Products; and ScholarlyArticle for peer-reviewed Source pages, otherwise Article.

Shared nested objects include Organization, WebSite, WebPage, Thing, CreativeWork, Brand, and Offer where applicable. JSON-LD citation carries evidence sources only. official_product_page sources are exposed through the Product node's subjectOf WebPage so product pages are not presented as proof of efficacy.

Use canonical URLs as stable citation targets.