gavel-mcp-server

Servidor MCP de Aletheia Analytics: interfaz nativa para agentes sobre el producto de datos Gavel.

Wrapper ligero de TypeScript alrededor de api.thegavel.io. Expone los datos de crédito de Gavel y los indicadores on-chain de Bitcoin como herramientas MCP para que los agentes impulsados por LLM (Claude Desktop, clientes IDE, agentes personalizados) puedan leer el producto de datos sin tener que construir integraciones REST a mano.

Estado

Las tres capas de la especificación de conserje de IA (aletheia-docs data/specs/mcp/ai_concierge.md) están activas, además de la superficie de indicadores y la resolución real de clave→nivel. Entregado por Runbook R18 y regido por la nota de decisiones data/specs/mcp/tier_and_scope_decisions_v1.md (MD1–MD12).

Capa A: estado de lectura

Capa B: modelo de fábrica (planos sin firmar; el usuario firma)

Capa C: catálogos

Superficie de datos

El invariante

Aletheia construye; el usuario firma. No hay superficie de firma en este código: ni cliente de wallet, ni cuenta, ni material de claves. viem se importa solo para encodeFunctionData. Eso es lo que hace que "Aletheia nunca firma" sea un hecho arquitectónico y no una promesa de política, y debe seguir así.

Igualmente importante: ninguna herramienta clasifica, puntúa o selecciona en nombre del usuario. Filtrar según criterios proporcionados por el usuario es un servicio de información; clasificar mediante un modelo interno es asesoramiento de inversión. find_auctions_matching_criteria se llama así deliberadamente, y el nombre no es cosmético.

Related MCP server: Stelar Signals MCP

Arquitectura

LLM Client → mcp.thegavel.io (this server) → api.thegavel.io (REST) → PostgreSQL
              [tool catalog, descriptions,        [authoritative endpoints]
               response shaping, auth, limits]

Fuente única de verdad: la API REST. El servidor MCP nunca consulta Postgres directamente. Las herramientas dan forma a las respuestas para el consumo de LLM (contenido de texto serializado en JSON) pero nunca reimplementan lógica de negocio. Cuando la API REST se actualiza, MCP hereda la actualización automáticamente.

Desarrollo local

# Install deps (Node 20+)
npm install

# Copy and edit env file
cp .env.example .env
nano .env  # set GAVEL_API_BASE_URL etc.

# Dev mode (tsx watch)
npm run dev

# Type check
npm run typecheck

# Build to dist/
npm run build

Apunte un cliente MCP de desarrollo (MCP Inspector, Claude Desktop con conector HTTP) a http://localhost:3002/mcp para probar las herramientas.

Despliegue

Destino: host Hetzner gavel-btc, junto a gavel-api.

# Local — build and stage
npm install
npm run build

# Copy to server
scp -r dist/ package.json package-lock.json deployment/ \
    root@gavel-btc:/root/gavel-mcp/

# On server — install runtime deps (not the full dev set)
ssh root@gavel-btc
cd /root/gavel-mcp
npm install --omit=dev

# Configure
cp .env.example .env
nano .env
# Set:
#   GAVEL_API_BASE_URL=https://api.thegavel.io  (public API, for tool reads)
#   GAVEL_API_INTERNAL_URL=http://127.0.0.1:4012  (loopback, for tier lookup)
#   INTERNAL_API_SECRET=<must match gavel-indexer/.env.mainnet>
#   PORT=3002
#   NODE_ENV=production

# Install systemd unit
cp deployment/gavel-mcp.service /etc/systemd/system/
systemctl daemon-reload
systemctl enable gavel-mcp.service
systemctl start gavel-mcp.service

# Verify
journalctl -u gavel-mcp -n 50 --no-pager
curl http://localhost:3002/health

# Reverse proxy
cp deployment/nginx-mcp.conf /etc/nginx/sites-available/mcp.thegavel.io
ln -s /etc/nginx/sites-available/mcp.thegavel.io \
      /etc/nginx/sites-enabled/mcp.thegavel.io
nginx -t && systemctl reload nginx

# TLS (Let's Encrypt)
certbot --nginx -d mcp.thegavel.io

# End-to-end check
curl https://mcp.thegavel.io/health

Configuración

Todos los ajustes viven en .env:

Modelo de niveles

La escalera es free / pro / enterprise, idéntica a la del producto (gavel-indexer/lib/tiers.js) y a lo que vende Stripe. El vocabulario original del andamiaje, anonymous / developer / professional / enterprise, era un segundo vocabulario para un mismo derecho y está retirado (MD1).

gavel-indexer/lib/api-keys.js es la autoridad sobre qué nivel tiene una clave. El MCP no abre su propio pool de base de datos; pregunta a GET /internal/resolve-tier a través de loopback, guarda en caché la respuesta durante 60 s y falla abierto a free ante cualquier error. Un MCP de datos que devuelve 500 porque la base de datos de claves tuvo un hipo es peor que uno que sirve brevemente como anónimo.

La aplicación está implementada pero DESACTIVADA

MCP_TIER_ENFORCEMENT tiene como valor predeterminado false, y ese es el estado correcto hoy. La monetización está bloqueada hasta la Puerta B (D16–D18): no construyas un muro de pago hasta que alguien haya pedido pagar. El Runbook A2 retiró la superficie comercial, y www.thegavel.io/pricing actualmente declara que el acceso a los datos es gratuito y abierto; por lo tanto, rechazar una herramienta y señalar al usuario a una página que niega que existan niveles sería un viaje que se refuta a sí mismo.

Con la bandera desactivada, requireTier aún resuelve el nivel real del llamador y registra lo que habría rechazado. Ese registro es la evidencia para M6, la condición de puerta de "¿alguien ha pedido realmente pagar?".

Antes de activarla, lee MD2. Hay dos interpretaciones incompatibles de lo que significa un MCP de pago: superficie completa de pago (lib/tiers.js lleva mcp: false en free) versus profundidad de pago (MD3, la respaldada). Son productos muy diferentes.

Qué es gratuito y por qué

Según MD3, heredando el mapa de ruta/profundidad de D5: el estado on-chain en bruto, el descubrimiento de subastas, el estado de la wallet, los indicadores on-chain de materias primas, el valor actual de cualquier evaluación derivada de Gavel y el historial son todos gratuitos. El historial es gratuito porque D9 retiró el límite de 30 días de la API REST, y el MCP no debe reintroducir una valla que la superficie que refleja ha abandonado. El límite de pago es la entrega masiva, que este servidor no ofrece.

La participación nunca está bloqueada (D3). Cada herramienta de las capas A/B/C es free: un posible postor nunca debe encontrarse con un muro de pago entre decidir pujar y poder hacerlo.

Los límites de tasa son protección de infraestructura, no un medidor de facturación (D2), y se aplican independientemente de la bandera de aplicación.

Redesplegar un cambio

npm run build            # tsc -> dist/ ; must be clean
systemctl restart gavel-mcp
systemctl is-active gavel-mcp
journalctl -u gavel-mcp -n 30 --no-pager

Este servicio es systemd, no pm2. pm2 en este host lleva quorum-mcp-testnet, un servicio diferente: pm2 restart gavel-mcp es un no-op que parece un despliegue exitoso. R18 v1 tenía esto mal; está registrado en el §8 de ese runbook.

El servicio ejecuta dist/, no src/, por lo que un cambio que no se compila es un cambio que no se despliega.

Añadir una herramienta

1. Crea src/tools/<category>/<name>.ts. Copia credit/yield-curve.ts como plantilla: es el ejemplo trabajado más limpio.

2. Define un esquema Zod para las entradas con .describe() en cada campo; esa descripción es lo que el LLM ve durante el descubrimiento de herramientas.

3. Escribe la descripción de la herramienta como una cadena de varias líneas. Comienza con qué es el indicador, da contexto interpretativo (sin recomendar nada) y documenta la forma de la respuesta. El SDK de MCP usa esto textualmente en el catálogo.

4. Cuerpo: requireTier(...) → upstreamGet(...) → devuelve { content: [{ type: 'text', text: JSON.stringify(...) }] }.

5. Registra la herramienta en src/tools/index.ts.

6. Añade una entrada a src/tools/discovery/list-onchain.ts (o al catálogo de descubrimiento equivalente para ese dominio).

Pruebas manuales

# 1. Health
curl -s http://localhost:3002/health | jq

# 2. MCP Inspector
npx @modelcontextprotocol/inspector
# Connect to http://localhost:3002/mcp
# Verify: tools/list returns 3 tools, get_yield_curve returns live data,
# get_mvrv returns a structured McpError "not found".

Licencia

Propietario © 2026 Aletheia Analytics SASU. Todos los derechos reservados.