elfa

Elfa MCP

Elfa API 用の Model Context Protocol サーバーです。暗号資産と株式に関する API v3 のイベント、ポジション、ランキングに加え、市場を監視して条件が満たされるとアクションを実行する条件エンジンの Auto、さらに X と Telegram の暗号資産ソーシャルインテリジェンスを提供します。

ホスト型サーバーにサインインする方法でも、API キーを使ってローカルで実行する方法でも、あらゆる MCP クライアントで利用できます。

インストール

ホスト型、Elfa にサインイン

クライアントにリモート MCP サーバーとして https://mcp.elfa.ai/mcp を追加し、ブラウザーで dev.elfa.ai アカウントを使って承認してください。コピーするキーもインストールも不要です。クライアントでサインインできない場合は、代わりにサーバーをローカルで実行してください。設定手順は MCP ガイドをご覧ください。

ローカル、API キー

dev.elfa.ai で API キーを取得してください。インストール手順は不要です。npx が必要に応じてサーバーを取得します。

ワンクリック

Claude Desktop

最新リリースから elfa-mcp-<version>.mcpb をダウンロードして開いてください。Claude Desktop がインストールし、API キーの入力を求め、最新の状態を維持します。ほかに設定するものはありません。

Claude Code

claude mcp add elfa --env ELFA_API_KEY=your-key -- npx -y @elfa-ai/mcp

Cursor、VS Code、Claude Desktop、その他のクライアント

{
  "mcpServers": {
    "elfa": {
      "command": "npx",
      "args": ["-y", "@elfa-ai/mcp"],
      "env": {
        "ELFA_API_KEY": "your-key"
      }
    }
  }
}

VS Code では "mcpServers" の代わりに "servers" を使います。それ以外は同じです。

動作を確認するには、*「今、暗号資産でトレンドになっているのは？」*と尋ねてください。

設定

変数	必須	用途
ELFA_API_KEY	はい	すべてのリクエストを認証します
ELFA_TIMEOUT	いいえ	リクエストのタイムアウト時間（ミリ秒）。デフォルトは 120000 です
ELFA_RETRIES	いいえ	失敗時の再試行回数。デフォルトは 0 です
ELFA_MCP_MAX_RESPONSE_CHARS	いいえ	レスポンスサイズの上限。デフォルトは 60000 です
ELFA_EXTRA_HEADERS	いいえ	上流に送信する追加ヘッダーの JSON オブジェクト。プロキシや本番環境以外で使用します

上流へのリクエストには、User-Agent: elfa-mcp/<version> (<transport>; client=<app>) が設定されます。stdio では、<app> はハンドシェイクで取得した MCP クライアントの名前とバージョンです。HTTP では、接続するクライアント独自の User-Agent ヘッダーが使われます。独自の値を送信するには、ELFA_EXTRA_HEADERS で User-Agent を設定してください。

タイムアウトが長く、再試行が無効になっているのは意図的です。解釈エンドポイントは LLM を利用しており、完了までに 1 分以上かかることがあります。また、試行ごとにクレジットが消費されるため、通知のない再試行が発生すると、確認できなかった呼び出しに対して再度課金されます。ELFA_RETRIES を増やすのは、低コストの測定エンドポイントを呼び出す場合に限ってください。

一部の MCP クライアントは、独自のタイムアウトを設定しており、多くの場合は約 60 秒です。narratives と market_chat はその時間を超えることがあります。クライアントが先に諦めた場合でも、リクエストは完了し、課金されます。

ツール

文書化されている /v2 と /v3 のすべての操作に対応する 16 個のツールです。

ツール	モード	コスト	機能
api_status	読み取り	無料	API キーのティア、クレジットの使用量と残りのリクエスト数、イベント・市場・コールを読み取れる期間を確認します。また、API に接続できることも確認します。
entities	読み取り	PAYG および Grow では 2026 年 10 月 31 日まで無料	ティッカー、$cashtag、名前、@handle、コントラクトアドレス、CoinGecko id、FIGI、CIK を、イベントやコールで使われるエンティティ ID に解決します。完全一致で照合するもので、検索ではありません。
events	読み取り	PAYG および Grow では 2026 年 10 月 31 日まで無料	暗号資産市場と株式市場で起きていることを確認します。level=events では何が起き、価格がどう反応したか、level=storylines では数日にわたって展開する 1 つの動向、level=arcs ではより大きな動きの中にまとめられたストーリーラインを取得できます。トピックで検索できます。
market	読み取り	PAYG および Grow では 2026 年 10 月 31 日まで無料	暗号資産または株式の市場全体の状況を確認します。view=mindshare は注目度に占める割合で資産を順位付けし、view=call_book は群衆のロング／ショートの傾きを時間ごとに示し、view=trending_contracts は投稿に貼り付けられた回数でコントラクトアドレスを順位付けします。
calls	読み取り	PAYG および Grow では 2026 年 10 月 31 日まで無料	投稿でアカウントが示したポジションを確認します。level=calls ではポジションを取る、または変更する各投稿、level=episodes では開始から終了までの各ポジションと投稿者の実績、level=positioning では現在の 1 つの資産に対する未決済のロングとショートを取得できます。
top_accounts	読み取り	PAYG および Grow では 2026 年 10 月 31 日まで無料	評判（他のアカウントからのエンゲージメント量）で X アカウントを順位付けします。metric を指定すると、予測者としての実績（alphaScore、hitRate、avgReturn）で順位付けします。
auto_build	読み取り	1 ＋ LLM の使用量	平易な言葉で書かれたモニタリング要求を EQL クエリに変換します。検証して有効化するための下書きを返しますが、それ自体で何かを有効化することはありません。
auto_validate	読み取り	無料	有効化する前に EQL の構文を確認してコストを見積もるか、あるいは特定の取引所でシンボルの市場データが利用可能かを確認します。
auto_query	読み取り	無料	Auto の読み取り機能です。クエリの一覧表示、クエリのポーリング、その実行履歴と LLM セッションの読み取りを行います。
auto_query_write	書き込み	作成には 5 ＋ LLM の使用量、キャンセルまたは削除は無料	Auto クエリを有効化、キャンセル、または削除します。有効化したクエリは無人で実行され、条件を満たすとアクションが発火します。
auto_draft	読み取り	無料	Auto の下書きの読み取り機能です。保存された下書きの一覧表示と、個々の下書きの読み取りを行います。下書きは有効化せずに保留されているクエリで、評価も発火もしません。
auto_draft_write	書き込み	クエリの作成と同じコストがかかる変換を除き無料	Auto の下書きを作成、更新、削除、または有効化します。下書きを変換すると、無人で実行されるライブクエリとして有効化されます。
mentions	読み取り	呼び出しごとに 1	X と Telegram のソーシャルメンションを取得します。mode=top はティッカーのメンションをエンゲージメントで順位付けし、mode=search はキーワードまたはアカウントで絞り込み、mode=news はトークンのニュースフィードを返します。これはニュース媒体の記事ではなく、ニュースソースとしてタグ付けされたアカウントの X 投稿です。
trending	読み取り	呼び出しごとに 1	ソーシャル上で注目を集めているものを確認します。scope=tokens はティッカー、scope=contracts_twitter または scope=contracts_telegram はコントラクトアドレスを対象にします。
narratives	読み取り	呼び出しごとに 5	出典リンク付きの文章によるナラティブ分析を取得します。scope=market は市場全体のナラティブを抽出し、scope=keywords は特定のキーワードに関するイベントを要約します。
market_chat	読み取り	速度により異なります	文章による市場分析を依頼します。会話形式のチャット、マクロ概要、クイックサマリー、トークンの紹介、トークン分析、アカウント分析に対応しています。

ツールとして公開されていないもの：

• chat-stream-v2 — ツール呼び出しでは結果が1つ返るため、ストリーミングを追加しても意味がありません。同じ分析は market_chat で行えます。
• auto-stream-queries-v2 — 長時間実行されるストリームに対応するツールはありません。auto_query でポーリングしてください。
• auto-stream-query-v2 — 長時間実行されるストリームに対応するツールはありません。auto_query でポーリングしてください。
• getAccountSmartStats-v2 — API では 2026 年 10 月 28 日にこのエンドポイントが廃止されるため、account_stats ツールは削除されます。アカウント単位の数値を返すツールはありません。mode=search を指定した mentions では、投稿アカウントごとの投稿エンゲージメント指標が返されます。

一部のツールはプランに依存します。現在、market_chat と API v3 ツールは、無料プランより上位のプランが必要です。起動時（stdio）またはリクエストごと（HTTP、キーごとに1分間キャッシュ）に、サーバーは /v2/key-status からキーのスコープを読み取ります。プランに含まれないツールも一覧には表示されますが、説明に上位プランが必要であることが記載されます。また、呼び出すと API を呼び出したりクレジットを消費したりせずに、アップグレード用リンクが返されます。3 秒以内にスコープを読み取れない場合は、通常どおりすべてのツールが一覧表示され、API が判定します。

ストリーミングエンドポイントは、SSE を利用できるアプリケーション向けに SDK から引き続き利用できます。

API v3

entities、events、market、calls、top_accounts は API v3 を読み取ります。対象は、イベント、ストーリーライン、アーク、コールブック、マインドシェア、トレンド契約、コール、コールエピソード、ポジショニング、ランキング済みアカウントです。これらは暗号資産と株式に対応しており、2026 年 10 月 31 日までは従量課金制プランと Grow プランで無料で利用でき、Enterprise キーでも利用できます。

• フィルターにはティッカーではなくエンティティ ID を指定します。まず entities で資産を解決し、その ID を再利用してください。
• 時刻は Unix 秒単位です。ミリ秒は受け付けられません。
• キーで遡って読み取れる期間は、プランによって異なります。api_status はその期間を historyFrom として返します。

生の API との違い

エージェントはコンテキスト内の情報量に応じてコストがかかるため、ツールでは API のすべてのデフォルト値をあえて引き継いでいません。

	API	ここでの値	理由
pageSize	エンドポイントに応じて 10～50、最大 100	10	すべて取得するのではなく、ページを順に取得します
v3 ツールの limit	エンドポイントに応じて 10 または 50、最大 30 または 200	10	すべて取得するのではなく、cursor を使ってページを取得します
チャットの speed	expert	fast	デフォルトではコストを抑え、深さが重要な場合は expert を指定します
メンションのフィールド	完全なレコード	重要度の高いフィールド	残りの情報を取得するには verbosity: "detailed" を渡します
大きなレスポンス	全体を返す	注記を添えて、収まるように切り詰める	1 回の呼び出しでコンテキストウィンドウを埋めないようにします

すべての値は呼び出しごとに設定できます。pageSize は最大 100、limit はエンドポイントごとの上限まで指定できます。

Auto

Auto クエリは自動で実行されます。一度有効にすると、クエリは評価を続け、再確認なしでアクションを実行します。

手順は 3 つです。

1. auto_build — 監視対象を平易な言葉で説明し、EQL を取得します
2. auto_validate — 構文を確認し、クレジットのコストを取得します
3. auto_query_write — クエリを有効にします

アクションでは、通知の送信、Webhook の呼び出し、Telegram ボットへのメッセージ送信、LLM 分析の実行ができます。

MCP にはプッシュチャネルがありません。method=get を指定して auto_query をポーリングし、呼び出しの間隔は返された pollAfterSeconds に従ってください。

リモートサーバー

同じサーバーは、ホスト型デプロイ向けに Streamable HTTP でも実行できます。

ELFA_MCP_TRANSPORT=http ELFA_MCP_PORT=3000 npx -y @elfa-ai/mcp

ステートレスです。セッションはなく、リクエストごとにサーバーインスタンスが 1 つ起動し、ロードバランサーの背後でも安全に動作します。認証情報は x-elfa-api-key リクエストヘッダーから取得し、ヘッダーがない場合は環境変数を使用します。または、OAuth サインインを利用できます（以下を参照）。

DNS リバインディング対策はデフォルトで有効です。サーバーが受け付けるのは、バインド先のループバック名、つまり localhost:PORT と 127.0.0.1:PORT のみです。これにより、上記のローカル実行はカバーされますが、それ以外は対象外です。異なる Host に応答するデプロイでは、応答する値を列挙する必要があります。

ELFA_MCP_ALLOWED_HOSTS=mcp.example.com

これには、パブリックドメイン、リバースプロキシ、サーバーのバインド先とは異なるポートにポートをマッピングするコンテナーが含まれます。リストに含まれない Host は 403 で拒否されます。

変数	必須	用途
ELFA_MCP_TRANSPORT	いいえ	Streamable HTTP で提供する場合は http、デフォルトは stdio
ELFA_MCP_HOST	いいえ	バインドアドレス、デフォルトは 127.0.0.1
ELFA_MCP_PORT	いいえ	バインドポート、デフォルトは 3000
ELFA_MCP_ALLOWED_HOSTS	いいえ	許可する Host のカンマ区切りリスト。デフォルトはバインド先のループバック名
ELFA_MCP_ALLOWED_ORIGINS	いいえ	許可する Origin のカンマ区切りリスト
ELFA_MCP_OPENAI_APPS_CHALLENGE	いいえ	OpenAI のプラグインポータルから取得したドメイン検証トークン。/.well-known/openai-apps-challenge でプレーンテキストとして提供

ブラウザーからサーバーを直接呼び出す場合は、ELFA_MCP_ALLOWED_ORIGINS も設定してください。これはホストの許可リストを置き換えるのではなく、補完するものです。リバインディングされたリクエストは同一オリジンであるため、許可リストで確認するための Origin ヘッダーを含みません。その場合、攻撃者のドメインを示す唯一のヘッダーは Host です。

OAuth サインイン

ホスト型サーバーでは、API キーを送信する代わりに、ブラウザー経由でクライアントにサインインさせることができます。ELFA_MCP_AUTH=oauth を設定すると、サーバーは MCP 認可仕様に準拠した OAuth リソースサーバーになります。

1. 認証情報なしのリクエストには、WWW-Authenticate チャレンジとともに 401 が返されます。
2. チャレンジは、/.well-known/oauth-protected-resource/mcp にある保護対象リソースのメタデータをクライアントに案内します。
3. メタデータには認可サーバーが記載されており、そこでユーザーがサインインします。
4. クライアントはその後、Authorization: Bearer <token> を送信します。
5. サーバーは、認可サーバーのイントロスペクションエンドポイントを使ってトークンを確認します。エンドポイントは、そのリクエストで使用する Elfa API キーを返すため、トークンが Elfa API に届くことはありません。

ELFA_MCP_TRANSPORT=http \
ELFA_MCP_AUTH=oauth \
ELFA_MCP_RESOURCE_URL=https://mcp.example.com/mcp \
ELFA_OAUTH_ISSUER=https://auth.example.com \
ELFA_OAUTH_INTROSPECTION_URL=https://auth.example.com/introspect \
ELFA_OAUTH_INTROSPECTION_TOKEN=... \
ELFA_MCP_ALLOWED_HOSTS=mcp.example.com \
npx -y @elfa-ai/mcp

変数	OAuth モードで必須	用途
ELFA_MCP_AUTH	はい	有効にするには oauth、デフォルトは apikey
ELFA_MCP_RESOURCE_URL	はい	このエンドポイントの正式な URL。トークンはこの値と完全に一致する URL 向けに発行されている必要があります
ELFA_OAUTH_ISSUER	はい	メタデータに記載された認可サーバー
ELFA_OAUTH_INTROSPECTION_URL	はい	トークンの確認先
ELFA_OAUTH_INTROSPECTION_TOKEN	はい	イントロスペクションエンドポイントに送信する Bearer トークン
ELFA_OAUTH_SCOPES	いいえ	公開するスコープのカンマ区切りリスト。デフォルトは elfa

注意事項：

• OAuth モードでも x-elfa-api-key ヘッダーを使用できます。
• OAuth モードでは ELFA_API_KEY は無視されるため、認証情報を持たない呼び出し元がサーバー自身のキーを使って実行されることはありません。
• 有効なトークンは最長 1 分間キャッシュされます。これにより、取り消されたトークンが引き続き有効になる時間を制限します。

安全性

認証の問題とクレジットの問題をすばやく見分けるには、api_status が最も手軽な方法です。

メンション、ニュース、ナラティブには、誰でも書き込めるサードパーティーのソーシャルテキストが含まれます。イベントはその内容をもとにまとめられ、v3 ツールにはサードパーティーのアセット名、アカウント名、チャンネル名が含まれます。サーバーはすべての応答でこれらを信頼できないデータとして示し、サーバーの指示では、モデルにデータとして扱うよう伝えています。こうした内容をもとにエージェントが auto_query_write を連鎖的に呼び出すことを許可する前に、この点を考慮してください。

開発

npm install
npm run build
npm run verify

npm run verify を実行すると、型チェック、テスト、仕様との差分チェック、ドキュメントチェックが実行されます。

manifest.json は、ドキュメントに記載されているすべての API 操作を、それに対応するツールに割り当てています。API にサーバーが処理しない操作が追加されると、npm run check:drift は失敗します。上記のツール一覧は、同じファイルから npm run docs:tools で生成されます。

リンク

• ドキュメント
• API キー
• TypeScript SDK

ライセンス

MIT