gavel-mcp-server

Aletheia Analytics MCPサーバー — Gavelデータプロダクトに対するエージェントネイティブなインターフェース。

api.thegavel.io の薄いTypeScriptラッパー。Gavelのクレジットデータとビットコインのオンチェーン指標をMCPツールとして公開し、LLM駆動のエージェント（Claude Desktop、IDEクライアント、カスタムエージェント）がRESTのグルーコードを手書きせずにデータプロダクトを読み取れるようにします。

ステータス

AIコンシェルジュ仕様（aletheia-docs data/specs/mcp/ai_concierge.md）の3層すべてが稼働しており、さらに指標サーフェスと実際のキー→ティア解決も含まれます。Runbook R18 によって提供され、決定メモ data/specs/mcp/tier_and_scope_decisions_v1.md（MD1–MD12）に準拠しています。

レイヤーA — 状態の読み取り

レイヤーB — ファクトリーモデル（未署名のブループリント。ユーザーが署名）

レイヤーC — カタログ

データサーフェス

不変条件

Aletheiaが構築し、ユーザーが署名する。 このコードベースには署名サーフェスがありません — ウォレットクライアントも、アカウントも、鍵素材もありません。viem は encodeFunctionData のためだけにインポートされています。これにより「Aletheiaは決して署名しない」がポリシーの約束ではなくアーキテクチャ上の事実となり、その状態を維持しなければなりません。

同様に重要なのは: ユーザーに代わってランク付け、スコアリング、選択を行うツールはありません。 ユーザー指定の基準によるフィルタリングは情報サービスであり、内部モデルによるランキングは投資アドバイスです。find_auctions_matching_criteria は意図的にそのように命名されており、その命名は表面的なものではありません。

Related MCP server: Stelar Signals MCP

アーキテクチャ

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

単一の真実源: REST API。MCPサーバーはPostgresを決して直接クエリしません。ツールはLLM消費用にレスポンスを整形します（JSON文字列化されたテキストコンテンツ）が、ビジネスロジックを再実装することはありません。REST APIがアップグレードされると、MCPは自動的にそのアップグレードを継承します。

ローカル開発

# 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

開発用MCPクライアント（MCP Inspector、HTTPコネクタ付きClaude Desktop）を http://localhost:3002/mcp に向けてツールを実行します。

デプロイ

ターゲット: gavel-btc Hetznerホスト、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

設定

すべての設定は .env にあります:

ティアモデル

ラダーは free / pro / enterprise — プロダクト（gavel-indexer/lib/tiers.js）およびStripeが販売するものと同一です。スキャフォールドの元の anonymous / developer / professional / enterprise は、1つの権限に対する2番目の語彙であり、廃止されました（MD1）。

gavel-indexer/lib/api-keys.js は、キーがどのティアであるかについての権威です。MCPは独自のデータベースプールを開かず、ループバック経由で GET /internal/resolve-tier に問い合わせ、回答を60秒間キャッシュし、エラー時には**free にフェイルオープン**します。キーデータベースが一時的に不調だったために500を返すデータMCPは、一時的に匿名を提供するものより悪いです。

強制は実装されているがOFF

MCP_TIER_ENFORCEMENT はデフォルトで false であり、それが今日の正しい状態です。収益化はGate B（D16–D18）までゲートされています: 誰かが支払いを求めるまでペイウォールを構築しないでください。Runbook A2は商用サーフェスを撤回し、www.thegavel.io/pricing は現在データアクセスが無料でオープンであると述べています — そのため、ツールを拒否してティアが存在しないと否定するページをユーザーに指し示すのは、自己矛盾する旅になるでしょう。

フラグがオフの場合でも、requireTier は呼び出し元の実際のティアを解決し、拒否したであろう内容をログに記録します。そのログはM6、つまり「実際に誰かが支払いを求めたか？」というゲート条件の証拠です。

フラグをオンにする前に、MD2を読んでください。有料MCPの意味には2つの互換性のない解釈があります — 全面有料（lib/tiers.js がfreeに mcp: false を持つ）と深度有料（MD3、支持されている方）です。これらは非常に異なるプロダクトです。

何が無料か、そしてその理由

MD3に従い、D5のルート/深度マップを継承: 生のオンチェーン状態、オークション発見、ウォレットステータス、コモディティのオンチェーン指標、Gavel由来の評価の現在値、および履歴はすべて無料です。履歴が無料なのは、D9が30日間のREST上限を廃止し、MCPがミラーリングするサーフェスが放棄したフェンスを再導入してはならないためです。有料の境界はバルク配信であり、このサーバーはそれを提供しません。

参加は決してゲートされません（D3）。レイヤーA/B/Cのすべてのツールは free です: 入札を希望する人は、入札を決定してから実行できるまでの間にペイウォールに遭遇してはなりません。

レート制限はインフラ保護であり、請求メーターではありません（D2）。強制フラグに関係なく適用されます。

変更の再デプロイ

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

このサービスはsystemdであり、pm2ではありません。 このホストのpm2は quorum-mcp-testnet という別のサービスを実行しています — pm2 restart gavel-mcp は成功したデプロイのように見えるノーオペレーションです。R18 v1はこれを誤っており、そのランブックの§8に記録されています。

サービスは src/ ではなく dist/ を実行するため、ビルドされていない変更はデプロイされていない変更です。

ツールの追加

1. src/tools/<category>/<name>.ts を作成します。credit/yield-curve.ts をテンプレートとしてコピーしてください — 最もクリーンな実例です。

2. 入力用のZodスキーマを定義し、すべてのフィールドに .describe() を付けます。その説明がツール発見時にLLMが見るものです。

3. ツールの説明を複数行の文字列として書きます。指標が何であるかを先頭に置き、解釈の文脈（何も推奨せずに）を与え、レスポンスの形状を文書化します。MCP SDKはこれをカタログでそのまま使用します。

4. 本体: requireTier(...) → upstreamGet(...) → { content: [{ type: 'text', text: JSON.stringify(...) }] } を返します。

5. src/tools/index.ts にツールを登録します。

6. src/tools/discovery/list-onchain.ts（またはそのドメインの同等の発見カタログ）にエントリを追加します。

手動テスト

# 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".

ライセンス

Proprietary © 2026 Aletheia Analytics SASU. All rights reserved.