Documentación técnica
Para desarrolladores y para quien lo configure a mano: el punto de acceso, las herramientas, los formatos de respuesta, los identificadores y los límites. Si solo quieres usarlo en tu asistente, basta con la guía de configuración.
Resumen
- Punto de acceso
https://btc.com/api/mcp- Transporte
- Streamable HTTP
- Autenticación
- Ninguna
- Acceso
- Solo lectura
| Elemento | Valor |
|---|---|
| Protocolo | MCP, especificación 2025-11-25 |
| Transporte | Streamable HTTP. Sin estado: cada solicitud recibe una respuesta JSON simple; sin flujo SSE |
| Servidor | btc-museum 1.0.0 |
| Instrucciones del servidor | Se envían al conectar: las cinco salas y sus identificadores, primero search y luego fetch, cómo citar, sin datos de mercado ni asesoramiento de inversión |
Herramientas
Hay dos herramientas, search y fetch. Sus nombres y formatos de respuesta siguen los requisitos de OpenAI para la investigación profunda de ChatGPT y también funcionan con otros clientes. Ambas están marcadas como de solo lectura (readOnlyHint); los parámetros y resultados se declaran en JSON Schema 2020-12.
searchsolo lectura
Busca elementos por palabras clave o una pregunta breve, en chino o en inglés. Devuelve hasta 10 resultados.
Parámetros
| Nombre | Tipo | Descripción |
|---|---|---|
query | string | Obligatorio. Palabras clave o una pregunta breve, de 1 a 200 caracteres |
locale | "zh" | "en" | Opcional. Idioma de títulos, fragmentos y enlaces: zh o en. Si se omite, el idioma de la consulta: chino si contiene caracteres chinos, si no, inglés; los campos sin versión en inglés vuelven al chino |
limit | integer | Opcional. Número de resultados, de 1 a 10 (10 por defecto) |
Devuelve
| Campo | Descripción |
|---|---|
results[].id | Identificador para pasar a fetch |
results[].title | Título |
results[].url | URL de la página del museo con un ancla que lleva al elemento |
results[].text | Fragmento breve sin fuentes; usa fetch antes de citarlo |
hint | Solo aparece cuando no hay resultados o cuando la pregunta pide precios en tiempo real, predicciones de precios o asesoramiento de inversión. Si no hay resultados, el museo no tiene nada sobre el tema; no uses elementos no relacionados como respuesta |
fetchsolo lectura
Lee el elemento completo a partir de un identificador devuelto por search.
Parámetros
| Nombre | Tipo | Descripción |
|---|---|---|
id | string | Obligatorio. Un identificador devuelto por search, por ejemplo narrative:events-pizza-day |
locale | "zh" | "en" | Opcional. Idioma del título, el texto completo y el enlace: zh o en (predeterminado en); cada campo sin versión en inglés vuelve al chino |
Devuelve
| Campo | Descripción |
|---|---|
id · title | El identificador y el título |
text | Texto completo en Markdown |
url | URL de la página del museo |
metadata.type · hall · locale · updatedAt | Tipo, sala, idioma y última actualización |
metadata.sources[] | Fuentes citadas por el museo, cada una con etiqueta y URL |
metadata.images[] | Imágenes que pueden mostrarse fuera del museo (de uso libre o hechas por el museo), con texto alternativo, crédito y licencia; las demás solo se muestran en las páginas del museo |
metadata.license · contributors | Vacío por ahora |
Si el identificador no existe o el elemento se ha retirado, el resultado lleva isError y una breve explicación.
Ejemplo de llamada
No hace falta un saludo inicial; envía directamente una solicitud JSON-RPC. La cabecera Accept debe incluir application/json y 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"}}}'Identificadores y enlaces
Todos los identificadores tienen la forma tipo:slug. Los slugs son fijos en todo el museo y en todos los entornos, y no cambian una vez publicados.
| Tipo | Contenido | El enlace lleva a |
|---|---|---|
hall | Sala | La página de la sala; fetch también lista los identificadores de sus relatos |
narrative | Relato | El elemento en la página de su sala |
exhibit | Pieza | El relato que la muestra; las piezas sin tarjeta enlazan a la página de su sala |
library | Documento de la biblioteca | La entrada en la biblioteca |
term | Término del glosario | La entrada en el glosario |
faq | Pregunta frecuente | La pregunta en la página de preguntas frecuentes, desplegada |
post | Artículo del blog | La página del artículo |
whitepaper | Sección del whitepaper | La sección en la guía del whitepaper de la sala Orígenes |
Cómo citar al museo
- Cuando uses contenido del museo, incluye la URL de la página que se devuelve con él.
- Usa solo las imágenes que aparecen en images de fetch; las demás solo se muestran en las páginas del museo por sus licencias.
- Este punto de acceso no ofrece precios en tiempo real, predicciones de precios ni asesoramiento de inversión.
- Cuando una cuestión es discutida, el museo expone las distintas posturas con fuentes. Mantén esas posturas al transmitir el contenido.
Límites y errores
| Cuándo | Respuesta |
|---|---|
| Más de 120 solicitudes por minuto desde una misma IP | 429 |
| Más de 600 solicitudes por minuto desde un mismo cliente (según User-Agent) | 429 |
| Más de 3000 solicitudes por minuto en total | 429 |
| Cuerpo de la solicitud de más de 64 KB | 413 |
| Una solicitud desde un navegador cuyo Origin no está en la lista permitida | 403 |
| GET o DELETE (solo se acepta POST; no hay flujo SSE) | 405 |
| Accept no incluye application/json y text/event-stream | 406 |
Las plataformas de IA llaman desde sus propios servidores, así que una IP puede representar a muchos usuarios; el límite por IP es amplio. No hagas extracción masiva.
Versiones y cambios
Versión actual: 1.0.0. Los nombres de las herramientas, los parámetros y los formatos de respuesta no cambiarán a la ligera una vez publicados; cualquier cambio se indicará aquí.
1.0.0 (2026-09-30): las herramientas search y fetch.