MCP · 기술 문서
기술 문서
개발자와 직접 연결하려는 분을 위한 문서입니다. 엔드포인트, 도구, 응답 형식, ID, 제한을 다룹니다. 어시스턴트에서 쓰기만 하려면 연결 안내로 충분합니다.
개요
- 주소
https://btc.com/api/mcp- 전송
- Streamable HTTP
- 인증
- 없음
- 권한
- 읽기 전용
| 항목 | 내용 |
|---|---|
| 프로토콜 | MCP, 사양 버전 2025-11-25 |
| 전송 | Streamable HTTP. 상태를 저장하지 않으며 요청마다 JSON으로 바로 응답합니다. SSE 스트림은 없습니다 |
| 서버 | btc-museum 1.0.0 |
| 연결 시 안내 | 연결할 때 보내는 안내: 다섯 전시실의 이름과 ID, search 후 fetch, 인용 규칙, 시세·투자 조언 미제공 |
도구
도구는 search와 fetch 두 가지뿐입니다. 이름과 응답 형식은 ChatGPT 심층 리서치에 대한 OpenAI 요구 사항을 따르며 다른 클라이언트에서도 쓸 수 있습니다. 둘 다 읽기 전용(readOnlyHint)으로 표시되어 있고, 매개변수와 결과는 JSON Schema 2020-12로 선언합니다.
search읽기 전용
키워드나 짧은 질문으로 항목을 찾습니다. 중국어와 영어 모두 가능하며 최대 10개를 돌려줍니다.
매개변수
| 이름 | 유형 | 설명 |
|---|---|---|
query | string | 필수. 키워드나 짧은 질문, 1–200자 |
locale | "zh" | "en" | 선택. 제목·요약·링크의 언어: zh 또는 en. 생략하면 질문의 언어(한자가 있으면 중국어, 아니면 영어). 영어판이 없는 필드는 중국어로 대체됩니다 |
limit | integer | 선택. 결과 개수, 1–10(기본 10) |
반환
| 필드 | 설명 |
|---|---|
results[].id | fetch에 넘길 ID |
results[].title | 제목 |
results[].url | 본관 페이지 URL. 앵커가 있어 해당 항목으로 바로 이동합니다 |
results[].text | 출처 없는 짧은 요약. 인용하기 전에 fetch로 전문을 읽으세요 |
hint | 결과가 없거나 실시간 가격·가격 예측·투자 조언을 물었을 때만 나타납니다. 결과가 없다는 것은 본관에 해당 내용이 없다는 뜻이니, 관련 없는 항목을 답으로 쓰지 마세요 |
fetch읽기 전용
search가 돌려준 ID로 전문을 읽습니다.
매개변수
| 이름 | 유형 | 설명 |
|---|---|---|
id | string | 필수. search가 돌려준 ID(예: narrative:events-pizza-day) |
locale | "zh" | "en" | 선택. 제목·전문·링크의 언어: zh 또는 en(기본 en). 영어판이 없는 필드는 항목별로 중국어로 대체됩니다 |
반환
| 필드 | 설명 |
|---|---|
id · title | ID와 제목 |
text | Markdown 전문 |
url | 본관 페이지 URL |
metadata.type · hall · locale · updatedAt | 유형, 전시실, 언어, 갱신 시각 |
metadata.sources[] | 본관이 표시한 출처. 각각 제목과 링크가 있습니다 |
metadata.images[] | 본관 밖에서도 보여 줄 수 있는 이미지(자유 이용 또는 본관 제작). 대체 텍스트·출처 표기·라이선스 포함. 그 밖의 이미지는 본관 페이지에서만 보여 줍니다 |
metadata.license · contributors | 현재는 비어 있음 |
ID가 없거나 게시가 내려간 항목이면 isError와 짧은 설명을 돌려줍니다.
호출 예시
핸드셰이크 없이 JSON-RPC 요청을 바로 보내면 됩니다. Accept에는 application/json과 text/event-stream을 모두 넣어야 합니다:
curl -s https://btc.com/api/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","arguments":{"query":"Bitcoin Pizza Day","locale":"en"}}}'ID와 링크
ID는 모두 “유형:slug” 형식입니다. slug는 박물관 전체와 모든 환경에서 고정이며 공개 후 바뀌지 않습니다.
| 유형 | 내용 | 링크 이동 위치 |
|---|---|---|
hall | 전시실 | 전시실 페이지. fetch는 전시실 안 각 전시 항목의 ID도 함께 돌려줍니다 |
narrative | 전시 해설 | 전시실 페이지의 해당 항목 |
exhibit | 전시품 | 그것을 보여 주는 전시 해설. 카드가 없는 전시품은 소속 전시실 페이지 |
library | 문헌 | 문헌관의 해당 항목 |
term | 용어 | 용어집의 해당 항목 |
faq | 자주 묻는 질문 | 자주 묻는 질문 페이지의 해당 질문(펼친 상태) |
post | 블로그 글 | 글 페이지 |
whitepaper | 백서 절 | “기원” 전시실 백서 해설의 해당 절 |
인용 규칙
- 본관 내용을 쓸 때는 함께 돌려받은 페이지 URL을 붙여 주세요.
- 이미지는 fetch의 images에 있는 것만 쓰세요. 그 밖의 이미지는 라이선스 때문에 본관 페이지에서만 보여 줍니다.
- 이 MCP 엔드포인트는 실시간 가격, 가격 예측, 투자 조언을 제공하지 않습니다.
- 논쟁이 있는 문제는 본관이 여러 견해를 출처와 함께 나란히 보여 줍니다. 내용을 전할 때 그 견해들을 함께 남겨 주세요.
제한과 오류
| 상황 | 응답 |
|---|---|
| 같은 IP에서 1분에 120회 초과 | 429 |
| 같은 클라이언트(User-Agent 기준)에서 1분에 600회 초과 | 429 |
| 전체 1분에 3000회 초과 | 429 |
| 요청 본문 64 KB 초과 | 413 |
| 브라우저에서 보낸 요청의 Origin이 허용 목록에 없음 | 403 |
| GET 또는 DELETE(POST만 받으며 SSE 스트림 없음) | 405 |
| Accept에 application/json과 text/event-stream이 모두 있지 않음 | 406 |
AI 플랫폼은 자체 서버에서 호출하므로 IP 하나 뒤에 많은 사용자가 있을 수 있습니다. 그래서 IP별 한도는 넉넉하게 잡았습니다. 대량 수집은 하지 말아 주세요.
버전과 변경
현재 버전은 1.0.0입니다. 도구 이름, 매개변수, 응답 형식은 공개 후 함부로 바꾸지 않으며, 바뀌면 여기에 적습니다.
1.0.0(2026-09-30): search와 fetch 두 도구.