Technical documentation
For developers and anyone setting it up by hand: the endpoint, tools, response formats, ids and limits. To just use it in your assistant, the setup guide is all you need.
Overview
- Endpoint
https://btc.com/api/mcp- Transport
- Streamable HTTP
- Authentication
- None
- Access
- Read-only
| Item | Value |
|---|---|
| Protocol | MCP, specification 2025-11-25 |
| Transport | Streamable HTTP. Stateless: every request gets a plain JSON response; no SSE stream |
| Server | btc-museum 1.0.0 |
| Server instructions | Sent on connect: the five halls and their ids, search first and then fetch, how to cite, no market data or investment advice |
Tools
There are two tools, search and fetch. Their names and response formats follow OpenAI’s requirements for ChatGPT deep research, and they work with other clients too. Both are marked read-only (readOnlyHint); parameters and results are declared in JSON Schema 2020-12.
searchread-only
Finds items by keywords or a short question, in Chinese or English. Returns up to 10 results.
Parameters
| Name | Type | Description |
|---|---|---|
query | string | Required. Keywords or a short question, 1–200 characters |
locale | "zh" | "en" | Optional. Language of titles, snippets and links: zh or en. If omitted, the language of the query: Chinese if it contains Chinese characters, otherwise English; fields without an English version fall back to Chinese |
limit | integer | Optional. How many results, 1–10 (default 10) |
Returns
| Field | Description |
|---|---|
results[].id | Id to pass to fetch |
results[].title | Title |
results[].url | Museum page URL with an anchor that lands on the item |
results[].text | Short snippet without sources; fetch the item before citing it |
hint | Only when there are no results, or when the question asks for live prices, price predictions or investment advice. No results means the museum has nothing on it; don’t treat unrelated items as an answer |
fetchread-only
Reads the full item for an id returned by search.
Parameters
| Name | Type | Description |
|---|---|---|
id | string | Required. An id returned by search, e.g. narrative:events-pizza-day |
locale | "zh" | "en" | Optional. Language of the title, full text and link: zh or en (default en); each field without an English version falls back to Chinese |
Returns
| Field | Description |
|---|---|
id · title | The id and title |
text | Full text in Markdown |
url | Museum page URL |
metadata.type · hall · locale · updatedAt | Type, hall, language and last update |
metadata.sources[] | Sources cited by the museum, each with a label and a URL |
metadata.images[] | Images that may be shown outside the museum (free to use or made by the museum), with alt text, credit and license; other images are only shown on the museum’s own pages |
metadata.license · contributors | Empty for now |
If the id doesn’t exist or the item has been unpublished, the result has isError set and a short explanation.
Example call
No handshake is needed; send a JSON-RPC request directly. The Accept header must list both application/json and 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"}}}'Ids and links
Every id has the form type:slug. Slugs are fixed across the museum and across environments, and won’t change once published.
| Type | Content | Link lands on |
|---|---|---|
hall | Hall | The hall page; fetch also lists the ids of the hall’s narrative items |
narrative | Narrative item | The item on its hall page |
exhibit | Exhibit | The narrative item that shows it; exhibits without a card link to their hall page |
library | Library document | The entry in the library |
term | Glossary term | The entry in the glossary |
faq | FAQ | The question on the FAQ page, opened |
post | Blog article | The article page |
whitepaper | Whitepaper section | The section in the whitepaper guide in the Origins hall |
Citing the museum
- When you use museum content, include the page URL returned with it.
- Only use the images listed in fetch’s images; other images are shown only on the museum’s pages because of their licenses.
- This endpoint gives no live prices, price predictions or investment advice.
- Where a question is disputed, the museum sets out the different views with sources. Please keep those views when you pass the content on.
Limits and errors
| When | Response |
|---|---|
| More than 120 requests a minute from one IP | 429 |
| More than 600 requests a minute from one client (by User-Agent) | 429 |
| More than 3000 requests a minute in total | 429 |
| Request body over 64 KB | 413 |
| A request from a browser whose Origin isn’t on the allowed list | 403 |
| GET or DELETE (only POST is accepted; there is no SSE stream) | 405 |
| Accept doesn’t list both application/json and text/event-stream | 406 |
AI platforms call from their own servers, so one IP can stand for many users; the per-IP limit is set generously. Please don’t scrape in bulk.
Versions and changes
Current version 1.0.0. Tool names, parameters and response formats won’t change casually once published; any change will be listed here.
1.0.0 (2026-09-30): the search and fetch tools.