Documentação técnica
Para desenvolvedores e para quem for configurar manualmente: o endpoint, as ferramentas, os formatos de resposta, os ids e os limites. Se você só quer usar no seu assistente, o guia de configuração basta.
Visão geral
- Endpoint
https://btc.com/api/mcp- Transporte
- Streamable HTTP
- Autenticação
- Nenhuma
- Acesso
- Somente leitura
| Item | Valor |
|---|---|
| Protocolo | MCP, especificação 2025-11-25 |
| Transporte | Streamable HTTP. Sem estado: cada requisição recebe uma resposta JSON simples; sem fluxo SSE |
| Servidor | btc-museum 1.0.0 |
| Instruções do servidor | Enviadas na conexão: as cinco salas e seus ids, primeiro search e depois fetch, como citar, sem dados de mercado nem aconselhamento de investimento |
Ferramentas
Há duas ferramentas, search e fetch. Os nomes e formatos de resposta seguem os requisitos da OpenAI para a pesquisa aprofundada do ChatGPT e também funcionam com outros clientes. As duas são marcadas como somente leitura (readOnlyHint); parâmetros e resultados são declarados em JSON Schema 2020-12.
searchsomente leitura
Encontra itens por palavras-chave ou uma pergunta curta, em chinês ou em inglês. Retorna até 10 resultados.
Parâmetros
| Nome | Tipo | Descrição |
|---|---|---|
query | string | Obrigatório. Palavras-chave ou uma pergunta curta, de 1 a 200 caracteres |
locale | "zh" | "en" | Opcional. Idioma de títulos, trechos e links: zh ou en. Se omitido, o idioma da consulta: chinês se tiver caracteres chineses, senão inglês; campos sem versão em inglês voltam para o chinês |
limit | integer | Opcional. Quantos resultados, de 1 a 10 (padrão 10) |
Retorno
| Campo | Descrição |
|---|---|
results[].id | Id a passar para fetch |
results[].title | Título |
results[].url | URL da página do museu com âncora que leva ao item |
results[].text | Trecho curto sem fontes; use fetch antes de citar |
hint | Só aparece quando não há resultados ou quando a pergunta pede preços em tempo real, previsões de preço ou aconselhamento de investimento. Sem resultados significa que o museu não tem nada sobre o tema; não use itens sem relação como resposta |
fetchsomente leitura
Lê o item completo a partir de um id retornado por search.
Parâmetros
| Nome | Tipo | Descrição |
|---|---|---|
id | string | Obrigatório. Um id retornado por search, por exemplo narrative:events-pizza-day |
locale | "zh" | "en" | Opcional. Idioma do título, do texto completo e do link: zh ou en (padrão en); cada campo sem versão em inglês volta para o chinês |
Retorno
| Campo | Descrição |
|---|---|
id · title | O id e o título |
text | Texto completo em Markdown |
url | URL da página do museu |
metadata.type · hall · locale · updatedAt | Tipo, sala, idioma e última atualização |
metadata.sources[] | Fontes citadas pelo museu, cada uma com rótulo e URL |
metadata.images[] | Imagens que podem ser exibidas fora do museu (de uso livre ou feitas pelo museu), com texto alternativo, crédito e licença; as demais só aparecem nas páginas do museu |
metadata.license · contributors | Vazio por enquanto |
Se o id não existir ou o item tiver sido despublicado, o resultado vem com isError e uma breve explicação.
Exemplo de chamada
Não é preciso handshake; envie direto uma requisição JSON-RPC. O cabeçalho Accept deve listar application/json e 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 e links
Todo id tem o formato tipo:slug. Os slugs são fixos em todo o museu e em todos os ambientes e não mudam depois de publicados.
| Tipo | Conteúdo | O link leva a |
|---|---|---|
hall | Sala | A página da sala; fetch também lista os ids das narrativas da sala |
narrative | Narrativa | O item na página da sala |
exhibit | Peça | A narrativa que a exibe; peças sem cartão levam à página da sala |
library | Documento da biblioteca | A entrada na biblioteca |
term | Termo do glossário | A entrada no glossário |
faq | Pergunta frequente | A pergunta na página de perguntas frequentes, aberta |
post | Artigo do blog | A página do artigo |
whitepaper | Seção do whitepaper | A seção no guia do whitepaper da sala Origens |
Como citar o museu
- Ao usar conteúdo do museu, inclua a URL da página retornada com ele.
- Use apenas as imagens listadas em images do fetch; as demais só aparecem nas páginas do museu por causa das licenças.
- Este endpoint não fornece preços em tempo real, previsões de preço nem aconselhamento de investimento.
- Quando uma questão é controversa, o museu apresenta as diferentes visões com fontes. Mantenha essas visões ao repassar o conteúdo.
Limites e erros
| Quando | Resposta |
|---|---|
| Mais de 120 requisições por minuto de um mesmo IP | 429 |
| Mais de 600 requisições por minuto de um mesmo cliente (por User-Agent) | 429 |
| Mais de 3000 requisições por minuto no total | 429 |
| Corpo da requisição acima de 64 KB | 413 |
| Uma requisição de navegador cujo Origin não está na lista permitida | 403 |
| GET ou DELETE (só POST é aceito; não há fluxo SSE) | 405 |
| Accept não lista application/json e text/event-stream | 406 |
As plataformas de IA chamam de seus próprios servidores, então um IP pode representar muitos usuários; o limite por IP é generoso. Não faça raspagem em massa.
Versões e mudanças
Versão atual: 1.0.0. Nomes de ferramentas, parâmetros e formatos de resposta não mudarão sem motivo depois de publicados; qualquer mudança será listada aqui.
1.0.0 (2026-09-30): as ferramentas search e fetch.