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.
https://ref.theseeker.io/mcp| URL | https://ref.theseeker.io/mcp |
|---|---|
| Transport | Streamable HTTP. Each response is a single JSON reply, and the server is stateless: it creates no sessions. |
| Methods | POST sends MCP requests. OPTIONS answers CORS preflight requests with 204. GET sends browsers to this page and returns 405 otherwise. |
| Required headers | content-type: application/jsonaccept: application/json, text/event-stream |
| Authentication | None. Only public references are served. |
| CORS | Every origin is allowed (Access-Control-Allow-Origin: *). |
| Rate limit | 120 requests per 60 seconds per IP. Past that, the server returns 429 with a Retry-After header. |
| Server name | theseeker-ref |
Try it with curl
Send both Accept values. If either one is missing, the server rejects the request with 406.
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"}}}'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":"tools/list","params":{}}'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":"tools/call","params":{"name":"search_references","arguments":{"query":"핀테크 대시보드","tags":["dark-mode"],"limit":10}}}'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
| Name | Type | Required | Default | Constraints | Description |
|---|---|---|---|---|---|
query | string | Optional | None | max 200 chars | Korean or English search text, up to 200 characters. |
tags | string[] | Optional | None | max 10 items | Up to 10 tag slugs; all must match. |
category | enumdashboardlandingmobilecomponentbrandingmotionother | Optional | None | None | Design category to filter by. |
author | string | Optional | None | max 50 chars | Author handle, up to 50 characters; leading @ is removed and case is ignored. |
sort | enumrelevancenewpopulardiverse | Optional | relevance | None | relevance (default: query rank, or diverse when there is no query), new, popular, or diverse (round-robin across authors). |
limit | integer | Optional | 10 | 1–30 | Number of references per page, from 1 to 30. |
cursor | string | Optional | None | max 200 chars | Pagination cursor, up to 200 characters; an invalid cursor starts at the first page. |
Examples
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "search_references",
"arguments": {
"query": "핀테크 대시보드",
"tags": [
"dark-mode"
],
"limit": 10
}
}
}{
"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
}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
| Name | Type | Required | Default | Constraints | Description |
|---|---|---|---|---|---|
id | integer | Required | None | None | Positive reference ID. |
include | enum[]analysismediatweetauthorsimilar | Optional | ["analysis","media"] | max 5 items | One to five sections to include; defaults to analysis and media. |
Examples
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "get_reference",
"arguments": {
"id": 142,
"include": [
"analysis",
"media",
"tweet",
"author",
"similar"
]
}
}
}{
"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"
}
]
}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
| Name | Type | Required | Default | Constraints | Description |
|---|---|---|---|---|---|
id | integer | Required | None | None | Positive reference ID. |
mediaIds | integer[] | Optional | None | max 6 items | One to six media IDs in the desired order. |
size | enumsmallmediumlarge | Optional | medium | None | Image size: small, medium or large. |
limit | integer | Optional | 4 | 1–6 | Maximum number of images, from 1 to 6. |
Examples
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "get_reference_images",
"arguments": {
"id": 142,
"mediaIds": [
401
],
"size": "medium"
}
}
}{
"content": [
{
"type": "text",
"text": "[0] mediaId=401 kind=image caption=Dashboard with key metrics and transaction history"
},
{
"type": "image",
"data": "UklGRg==",
"mimeType": "image/webp"
}
]
}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
| Name | Type | Required | Default | Constraints | Description |
|---|---|---|---|---|---|
ids | integer[] | Required | None | max 16 items | One to 16 reference IDs to compare; duplicates are ignored. |
columns | integer | Optional | 4 | 2–6 | Grid columns, from 2 to 6. |
Examples
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "get_contact_sheet",
"arguments": {
"ids": [
142,
151,
163,
170,
9999
],
"columns": 4
}
}
}{
"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"
}
]
}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
| Name | Type | Required | Default | Constraints | Description |
|---|---|---|---|---|---|
facet | enumlayoutmooddomaincomponentother | Optional | None | None | Tag facet to include. |
category | enumdashboardlandingmobilecomponentbrandingmotionother | Optional | None | None | Category to filter tag counts; category totals remain global. |
query | string | Optional | None | max 50 chars | Case-insensitive substring of tag slug or label, from 1 to 50 characters. |
Examples
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "list_tags",
"arguments": {
"category": "dashboard",
"facet": "layout"
}
}
}{
"categories": [
{
"slug": "dashboard",
"count": 28
}
],
"facets": [
{
"facet": "layout",
"tags": [
{
"slug": "dense-table",
"label": "고밀도 표",
"count": 8
}
]
}
]
}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
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "list_authors",
"arguments": {}
}
}{
"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"
}
]
}Several tools return items of the same shape. Field names match the response JSON exactly.
Items in items of search_references and similar of get_reference.
| Field | Type | Description |
|---|---|---|
id | integer | Number that identifies the reference. |
title | string | Korean title that captures what defines the design. |
summary | string | Short Korean summary of the design’s structure and impression. |
category | string | Design category, such as dashboard or landing page. |
tags | string[] | Tag slugs you can use in searches. |
palette | string[] | HEX values of the colors extracted from the design. |
author | string | The designer’s X handle. |
postedAt | string | When the original post was published. |
mediaCount | integer | Number of public images and videos. |
hasVideo | boolean | Whether a public video or GIF exists. |
thumbnailUrl | string | null | Small image or video poster URL of the first public media item. |
pageUrl | string | URL of the reference page you can open in a browser. |
Items in media of get_reference.
| Field | Type | Description |
|---|---|---|
mediaId | integer | Number that identifies the media item. |
index | integer | Position in the public media list, starting at 0. |
kind | image | video | gif | Media type: image, video or GIF. |
width | integer | null | Width of the media. |
height | integer | null | Height of the media. |
caption | string | null | Korean description of the image. |
captionEn | string | null | English description of the image. |
tags | string[] | Tags attached to this media item. |
urls | object | small, medium, large and orig URLs for images; poster and video URLs for videos and GIFs. |
Items in authors of list_authors.
| Field | Type | Description |
|---|---|---|
handle | string | The designer’s X handle. |
name | string | The name the designer displays. |
referenceCount | integer | Number of public references. |
videoCount | integer | Number of public references that hold a video. |
lastPostedAt | string | null | When the most recent public post was published. |
bio | string | null | The designer’s profile bio. |
pageUrl | string | URL of the designer’s page on TheSeeker Reference. |
xUrl | string | The designer’s X profile URL. |
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.
| Code | Layer | Meaning |
|---|---|---|
RATE_LIMITED | Tool result | Contact sheet build and queue capacity is full; retry shortly. |
NOT_FOUND | Tool result | The requested reference does not exist or is not public. |
VALIDATION | Tool result | A value passed to the tool is outside the allowed range or format. |
INTERNAL | Tool result | Something went wrong during the lookup. Try again shortly. |
400/-32600 | HTTP response | At most one get_contact_sheet call is allowed per batch. |
405 | HTTP response | HTTP method not allowed. Use POST for tool calls. |
406 | HTTP response | Include both application/json and text/event-stream in the Accept header. |
429/-32029 | HTTP response | Per-minute request limit exceeded. A batch counts once per tools/call (at least once). Retry after the time given in Retry-After. |