Docs menuTool reference

MCP reference

Tool reference

The arguments and response formats of the 6 tools the TheSeeker Reference MCP server provides. Every tool is read-only, so repeating a request never changes the data.

POSTEndpointhttps://ref.theseeker.io/mcp

Endpoint spec

URLhttps://ref.theseeker.io/mcp
TransportStreamable HTTP. Each response is a single JSON reply, and the server is stateless: it creates no sessions.
MethodsPOST sends MCP requests. OPTIONS answers CORS preflight requests with 204. GET sends browsers to this page and returns 405 otherwise.
Required headerscontent-type: application/jsonaccept: application/json, text/event-stream
AuthenticationNone. Only public references are served.
CORSEvery origin is allowed (Access-Control-Allow-Origin: *).
Rate limit120 requests per 60 seconds per IP. Past that, the server returns 429 with a Retry-After header.
Server nametheseeker-ref

Try it with curl

Send both Accept values. If either one is missing, the server rejects the request with 406.

bash
curl -sS https://ref.theseeker.io/mcp -H 'content-type: application/json' -H 'accept: application/json, text/event-stream' -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1.0.0"}}}'

search_references

Read-onlySearch references

Finds public references by keyword, tag, category and designer. Each result carries a preview image and the original page URL.

Description sent to the model

Search public design references by Korean or English text, tags (all-of), category and author. All query terms must match first; when nothing matches, the server automatically retries with any-of prefix matching and reports matchMode:"any". Keep queries to 1–3 short keywords or use tag slugs from list_tags. Without a query the default order is diverse (one top reference per author before repeats); new and popular are also available. Returns total, matchMode, appliedSort, cards and a pagination cursor; an empty result adds suggestedTags and a hint.

Arguments

NameTypeRequiredDefaultConstraintsDescription
querystringOptionalNonemax 200 charsKorean or English search text, up to 200 characters.
tagsstring[]OptionalNonemax 10 itemsUp to 10 tag slugs; all must match.
categoryenumdashboardlandingmobilecomponentbrandingmotionotherOptionalNoneNoneDesign category to filter by.
authorstringOptionalNonemax 50 charsAuthor handle, up to 50 characters; leading @ is removed and case is ignored.
sortenumrelevancenewpopulardiverseOptionalrelevanceNonerelevance (default: query rank, or diverse when there is no query), new, popular, or diverse (round-robin across authors).
limitintegerOptional101–30Number of references per page, from 1 to 30.
cursorstringOptionalNonemax 200 charsPagination cursor, up to 200 characters; an invalid cursor starts at the first page.

Examples

Example request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_references",
    "arguments": {
      "query": "핀테크 대시보드",
      "tags": [
        "dark-mode"
      ],
      "limit": 10
    }
  }
}
Example response
{
  "total": 1,
  "matchMode": "all",
  "appliedSort": "rank",
  "items": [
    {
      "id": 142,
      "title": "어두운 화면에 지표를 촘촘히 담은 금융 대시보드",
      "summary": "중요한 수치를 상단에 모으고 차트와 거래 내역을 한눈에 비교할 수 있도록 배치했습니다.",
      "category": "dashboard",
      "tags": [
        "dark-mode",
        "dense-table"
      ],
      "palette": [
        "#101014",
        "#c8f169"
      ],
      "author": "designarchive",
      "postedAt": "2026-03-12T09:30:00.000Z",
      "mediaCount": 1,
      "hasVideo": false,
      "thumbnailUrl": "https://pbs.twimg.com/media/Gh7Vq4XWAAIu9nB?format=webp&name=small",
      "pageUrl": "https://ref.theseeker.io/r/142"
    }
  ],
  "nextCursor": null
}

get_reference

Read-onlyGet reference

Reads only the parts of a reference you pick: analysis, media, original post, designer and similar work.

Description sent to the model

Read a public reference by ID. Select only the analysis, media, tweet, author or similar sections you need.

Arguments

NameTypeRequiredDefaultConstraintsDescription
idintegerRequiredNoneNonePositive reference ID.
includeenum[]analysismediatweetauthorsimilarOptional["analysis","media"]max 5 itemsOne to five sections to include; defaults to analysis and media.

Examples

Example request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_reference",
    "arguments": {
      "id": 142,
      "include": [
        "analysis",
        "media",
        "tweet",
        "author",
        "similar"
      ]
    }
  }
}
Example response
{
  "id": 142,
  "pageUrl": "https://ref.theseeker.io/r/142",
  "analysis": {
    "title": "어두운 화면에 지표를 촘촘히 담은 금융 대시보드",
    "titleEn": "A dense dark fintech dashboard",
    "summary": "중요한 수치를 상단에 모으고 차트와 거래 내역을 한눈에 비교할 수 있도록 배치했습니다.",
    "summaryEn": "Key figures, charts and transactions are arranged for quick comparison.",
    "description": "상단에는 주요 지표를 두고 아래에는 시계열 차트와 거래 표를 나란히 배치해 탐색 흐름을 단순하게 만들었습니다.",
    "descriptionEn": "Key metrics lead into a time-series chart and transaction table for a clear reading path.",
    "category": "dashboard",
    "tags": [
      {
        "slug": "dark-mode",
        "label": "다크 모드",
        "facet": "mood"
      }
    ],
    "vibe": [
      "minimal",
      "dark-mode"
    ],
    "palette": [
      {
        "hex": "#101014",
        "name": "짙은 먹색"
      }
    ],
    "hasText": true,
    "notes": null,
    "confidence": 0.94
  },
  "media": [
    {
      "mediaId": 401,
      "index": 0,
      "kind": "image",
      "width": 1200,
      "height": 800,
      "caption": "주요 지표와 거래 내역이 함께 보이는 대시보드 화면",
      "captionEn": "Dashboard with key metrics and transaction history",
      "tags": [
        "dashboard",
        "chart"
      ],
      "urls": {
        "small": "https://pbs.twimg.com/media/Gh7Vq4XWAAIu9nB?format=webp&name=small",
        "medium": "https://pbs.twimg.com/media/Gh7Vq4XWAAIu9nB?format=webp&name=medium",
        "large": "https://pbs.twimg.com/media/Gh7Vq4XWAAIu9nB?format=webp&name=large",
        "orig": "https://pbs.twimg.com/media/Gh7Vq4XWAAIu9nB?format=webp&name=orig"
      }
    }
  ],
  "tweet": {
    "text": "Exploring a calmer way to read financial data.",
    "url": "https://x.com/designarchive/status/1899212345678901234",
    "postedAt": "2026-03-12T09:30:00.000Z",
    "metrics": {
      "likes": 240,
      "retweets": 38,
      "replies": 12,
      "views": 18400
    }
  },
  "author": {
    "handle": "designarchive",
    "name": "Design Archive",
    "bio": "Digital product designer",
    "followers": 8200,
    "referenceCount": 17,
    "pageUrl": "https://ref.theseeker.io/authors/designarchive",
    "xUrl": "https://x.com/designarchive"
  },
  "similar": [
    {
      "id": 142,
      "title": "어두운 화면에 지표를 촘촘히 담은 금융 대시보드",
      "summary": "중요한 수치를 상단에 모으고 차트와 거래 내역을 한눈에 비교할 수 있도록 배치했습니다.",
      "category": "dashboard",
      "tags": [
        "dark-mode",
        "dense-table"
      ],
      "palette": [
        "#101014",
        "#c8f169"
      ],
      "author": "designarchive",
      "postedAt": "2026-03-12T09:30:00.000Z",
      "mediaCount": 1,
      "hasVideo": false,
      "thumbnailUrl": "https://pbs.twimg.com/media/Gh7Vq4XWAAIu9nB?format=webp&name=small",
      "pageUrl": "https://ref.theseeker.io/r/142"
    }
  ]
}

get_reference_images

Read-onlyGet reference images

Shows the images and video posters of chosen references directly. An error on one image does not block the others.

Description sent to the model

Fetch the full images or video posters of one reference as image content blocks. Use it after get_contact_sheet, only for the 3–5 references you actually use; individual image failures are reported as text.

Arguments

NameTypeRequiredDefaultConstraintsDescription
idintegerRequiredNoneNonePositive reference ID.
mediaIdsinteger[]OptionalNonemax 6 itemsOne to six media IDs in the desired order.
sizeenumsmallmediumlargeOptionalmediumNoneImage size: small, medium or large.
limitintegerOptional41–6Maximum number of images, from 1 to 6.

Examples

Example request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_reference_images",
    "arguments": {
      "id": 142,
      "mediaIds": [
        401
      ],
      "size": "medium"
    }
  }
}
Example response
{
  "content": [
    {
      "type": "text",
      "text": "[0] mediaId=401 kind=image caption=Dashboard with key metrics and transaction history"
    },
    {
      "type": "image",
      "data": "UklGRg==",
      "mimeType": "image/webp"
    }
  ]
}

get_contact_sheet

Read-onlyGet contact sheet

Puts up to 16 candidate references on one image for comparison. Each cell shows its reference id.

Description sent to the model

Compare up to 16 candidate references visually in one JPEG grid image: one tile per reference with its first public image or video poster, labelled #id. Returns a text legend with each tile's pageUrl, then the image. Use it before get_reference_images.

Arguments

NameTypeRequiredDefaultConstraintsDescription
idsinteger[]RequiredNonemax 16 itemsOne to 16 reference IDs to compare; duplicates are ignored.
columnsintegerOptional42–6Grid columns, from 2 to 6.

Examples

Example request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_contact_sheet",
    "arguments": {
      "ids": [
        142,
        151,
        163,
        170,
        9999
      ],
      "columns": 4
    }
  }
}
Example response
{
  "content": [
    {
      "type": "text",
      "text": "Contact sheet: 4 tiles in 4 columns, row-major; image labels are reference ids.\n[1] #142 어두운 화면에 지표를 촘촘히 담은 금융 대시보드 — https://ref.theseeker.io/r/142\n[2] #151 밝고 단정한 캘린더 앱 — https://ref.theseeker.io/r/151\n[3] #163 벤토 그리드 랜딩 페이지 — https://ref.theseeker.io/r/163\n[4] #170 여백이 넓은 포트폴리오 — https://ref.theseeker.io/r/170\nskipped #9999: NOT_FOUND"
    },
    {
      "type": "image",
      "data": "/9j/4AAQ",
      "mimeType": "image/jpeg"
    }
  ]
}

list_tags

Read-onlyList tags

Explores public reference counts by category, and the tags. Narrow the tags by category or search term.

Description sent to the model

List global visible reference category counts and tag facets, optionally filtering facets by category, facet or substring.

Arguments

NameTypeRequiredDefaultConstraintsDescription
facetenumlayoutmooddomaincomponentotherOptionalNoneNoneTag facet to include.
categoryenumdashboardlandingmobilecomponentbrandingmotionotherOptionalNoneNoneCategory to filter tag counts; category totals remain global.
querystringOptionalNonemax 50 charsCase-insensitive substring of tag slug or label, from 1 to 50 characters.

Examples

Example request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_tags",
    "arguments": {
      "category": "dashboard",
      "facet": "layout"
    }
  }
}
Example response
{
  "categories": [
    {
      "slug": "dashboard",
      "count": 28
    }
  ],
  "facets": [
    {
      "facet": "layout",
      "tags": [
        {
          "slug": "dense-table",
          "label": "고밀도 표",
          "count": 8
        }
      ]
    }
  ]
}

list_authors

Read-onlyList authors

Shows the bio and reference count of every designer with public references.

Description sent to the model

List authors with at least one public reference, including reference and video counts and profile URLs.

Arguments

No input arguments. Call it with an empty object.

Examples

Example request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_authors",
    "arguments": {}
  }
}
Example response
{
  "authors": [
    {
      "handle": "designarchive",
      "name": "Design Archive",
      "referenceCount": 17,
      "videoCount": 3,
      "lastPostedAt": "2026-03-12T09:30:00.000Z",
      "bio": "Digital product designer",
      "pageUrl": "https://ref.theseeker.io/authors/designarchive",
      "xUrl": "https://x.com/designarchive"
    }
  ]
}

Data model

Several tools return items of the same shape. Field names match the response JSON exactly.

ReferenceItem

Items in items of search_references and similar of get_reference.

FieldTypeDescription
idintegerNumber that identifies the reference.
titlestringKorean title that captures what defines the design.
summarystringShort Korean summary of the design’s structure and impression.
categorystringDesign category, such as dashboard or landing page.
tagsstring[]Tag slugs you can use in searches.
palettestring[]HEX values of the colors extracted from the design.
authorstringThe designer’s X handle.
postedAtstringWhen the original post was published.
mediaCountintegerNumber of public images and videos.
hasVideobooleanWhether a public video or GIF exists.
thumbnailUrlstring | nullSmall image or video poster URL of the first public media item.
pageUrlstringURL of the reference page you can open in a browser.

MediaEntry

Items in media of get_reference.

FieldTypeDescription
mediaIdintegerNumber that identifies the media item.
indexintegerPosition in the public media list, starting at 0.
kindimage | video | gifMedia type: image, video or GIF.
widthinteger | nullWidth of the media.
heightinteger | nullHeight of the media.
captionstring | nullKorean description of the image.
captionEnstring | nullEnglish description of the image.
tagsstring[]Tags attached to this media item.
urlsobjectsmall, medium, large and orig URLs for images; poster and video URLs for videos and GIFs.

AuthorEntry

Items in authors of list_authors.

FieldTypeDescription
handlestringThe designer’s X handle.
namestringThe name the designer displays.
referenceCountintegerNumber of public references.
videoCountintegerNumber of public references that hold a video.
lastPostedAtstring | nullWhen the most recent public post was published.
biostring | nullThe designer’s profile bio.
pageUrlstringURL of the designer’s page on TheSeeker Reference.
xUrlstringThe designer’s X profile URL.

Error codes

Tool errors come back as a result with isError: true, and its body is JSON holding error.code and error.message. HTTP errors mean the request itself was rejected before any tool ran.

CodeLayerMeaning
RATE_LIMITEDTool resultContact sheet build and queue capacity is full; retry shortly.
NOT_FOUNDTool resultThe requested reference does not exist or is not public.
VALIDATIONTool resultA value passed to the tool is outside the allowed range or format.
INTERNALTool resultSomething went wrong during the lookup. Try again shortly.
400/-32600HTTP responseAt most one get_contact_sheet call is allowed per batch.
405HTTP responseHTTP method not allowed. Use POST for tool calls.
406HTTP responseInclude both application/json and text/event-stream in the Accept header.
429/-32029HTTP responsePer-minute request limit exceeded. A batch counts once per tools/call (at least once). Retry after the time given in Retry-After.