Apiosk

Apiosk MCP

@apiosk/mcp 3.0.0 では、Apiosk の Ask ワークフローを Claude、Codex などの MCP ホストで利用できます。質問し、該当するソースを比較し、入力内容と合計金額を確認して、そのリクエストを承認し、保存された結果を調べます。検出、プランニング、価格、実行、エビデンスには既存の Gateway を使用します。

MCP1 カードの URL、接続 ID、トークン形式、キャッシュされた Ask ツールのシグネチャには、引き続き互換性があります。互換性対応の操作はカード内に限定され、新しいモデル接続では引き続き Ask が最初に表示されます。旧形式と新形式の承認呼び出しは、どちらも同じ永続的な承認レコードを共有します。

デフォルトでは、質問に応じてソースを検出します。カタログ全体を参照するフローはありません。たとえば、「ASML はどのような事業を行っていますか？」と尋ねられた場合、まずその質問で apiosk_ask を呼び出し、該当するソースを表示します。モデルの一般知識は Apiosk の結果ではありません。

このリポジトリは、obcraft/apiosk-mcp の正規実装です。バージョン付きのソースとマニフェストがあっても、このバージョンがデプロイ、公開、またはホストにインストールされたことを示すものではありません。

Ask の操作と埋め込みコンポーネント

サーバーは、36 個の公開ツールと 6 個の非公開コンポーネント操作、保存済みリクエストのリソース、および Ask プロンプトを公開します。実際の App Ask React コンポーネントとデザイントークンは src/ask-page/ にベンダー提供されており、自己完結型の埋め込みリソースにコンパイルされます。ローカルテスターは同じリソースを読み込みます。src/ask-ui/ には元の MCP トランスポートと互換レンダラーが保持されており、すべての操作で永続的な保存済みリクエストおよび承認ジャーナルが引き続き使用されます。

ソースの検出では、App のフィルタリング、重複排除、プロバイダーの順序付けが使用されます。提示されたエンドポイント記述子は、一致するソースを補足しますが、無関係なカタログ項目は追加しません。アカウントの表示通貨は、Gateway の読み取り専用 /v2/display-context から取得します。見積もりの原子的な金額は変更されません。ソースを編集した後は、npm run build:ask-page で埋め込みバンドルを再ビルドしてください。

ソースを手動で選択すると、選択した各ネイティブエンドポイントに対し、App と完全に同じ入力値で準備が行われます。接続済みクライアントは /v2/ask/source/prepare を使用します。この操作では、接続に継続的な支出ルールが設定されている場合でも、明示的な承認が必要です。MCP はこれらの保存済み見積もりを、確認済みの 1 つの上限額にまとめます。準備によってデータが購入されることはありません。

MCP Apps および ChatGPT 互換メタデータは、埋め込みリソースを識別します。モデルに表示される結果には、簡潔なソース識別子、ステータス、必要な入力、および正確な承認内容が含まれます。コンポーネントの完全なデータは _meta.apiosk_card_data で別途送信されるため、大きなソーススキーマや生のレスポンスツリーでモデルのコンテキストがあふれることはありません。保存済みのエビデンスは、引き続き結果ツールとエビデンスツールから利用できます。

埋め込みコンポーネントに対応したホストでは、インタラクティブなカードを表示できます。テキストのみのホストでは、構造化された結果が提供され、公開ツールが使用されます。サポートとレンダリングは引き続きホストに依存します。ローカルテストに合格しても、インストール済みの Claude、Codex、ChatGPT で受け入れられるとは限りません。読み取り専用の HTML エクスポートは、インタラクティブなカードとは別のものです。

操作	ツール
Ask と一致するソースを確認する	apiosk_ask、apiosk_sources
ソース入力を編集し、合計を 1 つにまとめて準備する	apiosk_prepare
正確な見積もりを確認し、明示的に承認する	apiosk_approve
進捗の確認、価格の更新、選択肢や不足している入力の提供	apiosk_status、apiosk_requote、apiosk_continue
中断された検出の再試行とタスクオプションの調整	apiosk_retry_search、apiosk_task_options、apiosk_source_selection、apiosk_analysis_quote
保存済みの回答、エビデンス、ページ、ダウンロード、会話	apiosk_result、apiosk_evidence、apiosk_result_page、apiosk_artifact、apiosk_chats
購入済みのエビデンスを使ったフォローアップ	apiosk_follow_up
接続済みアプリの操作と定期チェック	統合／操作のレビュー用ツール、ネイティブの定期実行ツール、apiosk_schedule_handoff

apiosk_ask のデフォルトは mode: "sources" です。自動プランニングは mode: "automatic" で使用できます。準備によって購入が承認されることはありません。実行を承認する前に、返された通貨、合計上限額、ソース、不足項目、有効期限、承認 ID を確認してください。表示される選択肢には、Ask ページと同じ購入可能性フィルターが使用されます。検出メタデータとソースの選択肢は、購入済みの調査結果ではありません。

結果では、意味のある 0 や false の値を含め、ソースの日付、引用、対象範囲、不足項目が保持されます。ローカルのフィルター、並べ替え、チャート／テーブル表示、保存済みページ、エクスポートでは、保存済みデータが再利用されます。フォローアップでは可能な限り購入済みのエビデンスが使用されます。新しいデータが必要な場合は、別途レビューされるリクエストが作成されます。

このチェックアウトから実行する

Node.js 22.16 以降と、認証済みの Apiosk 接続が必要です。このワークスペースでの正式なディレクトリは /Users/olivier/Documents/Apiosk/Production/Main/mcp です。

cd /Users/olivier/Documents/Apiosk/Production/Main/mcp
npm ci
npm run check
npm test

プライベート環境またはローカルの .env にある既存の Apiosk 認証情報を使用してください。コミットするサンプルに認証情報を含めないでください。ランタイムのエントリーポイントは環境変数を読み取ります。.env を明示的に読み込むには、Node の --env-file オプションを使用してください。

エントリーポイント	用途
node index.mjs / npm run start:stdio	ローカルの stdio MCP。設定済みの接続トークンを使用します。apiosk、apiosk-mcp、apiosk-mcp-server パッケージコマンドはこのエントリーポイントを使用します。
node server.mjs / npm start	OAuth メタデータ、登録、認可、トークンの各ルートを備えた正式なホスト型 HTTP サーバー。デフォルトのポートは 3000 です。認証が必要な従来の SSE エンドポイントも引き続き利用できます。
node bin/mcp-2.mjs --http --host 127.0.0.1 --port 3012	ローカルテスト用の最小限のベアラートークン HTTP トランスポート。この互換性のためのファイル名は内部用として残されています。このエントリーポイントでは、ホスト型 OAuth フローは提供されません。

プライベートな .env を使って stdio を実行する場合：

node --env-file=.env index.mjs

ホスト型サーバーでは、既存の OAuth ID とシークレットの設定が維持されます。起動には署名シークレットを含むこれらの設定が必要です。ローカルファイルに設定がある場合は、node --env-file=.env server.mjs を使用してください。HTTP クライアントは、各リクエストをそれぞれ認証します。サーバー全体で共有するトークンが HTTP 呼び出し元に貸し出されることはありません。/health が示すのはプロセスの健全性であり、Gateway やソースの準備状況ではありません。

ローカルテスター

テスターは http://127.0.0.1:3013 で動作し、デフォルトでは MCP エンドポイント http://127.0.0.1:3012/mcp に接続します。最小限のローカル MCP トランスポートを、1 つ目のターミナルで起動します：

node --env-file=.env bin/mcp-2.mjs --http --host 127.0.0.1 --port 3012

別のターミナルでテスターを起動します：

npm run dev:chat

代わりにポート 3000 の正式なホスト型サーバーをテストするには：

MCP_DEV_URL=http://127.0.0.1:3000/mcp npm run dev:chat

テスターはこのチェックアウトの .env、.env.v2.local、.env.dev.local を読み込み、継承した環境変数を優先します。既存の MCP_DEV_TOKEN と OPENROUTER_API_KEY を再利用します。ローカルに OpenRouter キーが設定されていない場合は、隣接する gateway/.env からプロバイダーキーのみを読み込みます（OPENROUTER_API_KEY、次に INTENT_API_KEY）。Gateway の実行フラグを継承したり、それらの認証情報を変更したりすることはありません。MCP_DEV_PORT、MCP_DEV_URL、MCP_DEV_MODEL でテスターのデフォルト値を上書きできます。カスタム Gateway イベントオリジンを指定するには、MCP_DEV_GATEWAY_URL を設定します。埋め込みカードとテスターは、ライブステータス更新に同じ固定オリジンポリシーを使用します。

質問する前に、対象のアカウントに接続してください。テスターは最初の質問に対して apiosk_ask を呼び出し、他のホストに提供されるものと同じ埋め込みコンポーネントを表示します。最初の検出では、モデルが作成する追加の回答を返さず、信頼できる Ask カードで停止します。その後のモデルによる続きの処理には、ツールの結果を制限付きで投影したデータが渡されます。カードの全データはコンポーネントから引き続き利用できます。モデル API の使用と、承認済みソースの購入は別々の操作です。

Claude または Codex に接続する

examples/codex.toml、examples/claude-code.mcp.json、または examples/claude-desktop.json を使用し、設定済みの他のサーバーはそのまま維持してください。インストール環境に合わせて絶対パスを調整し、トークンはプライベートな設定または環境変数に保管してください。これらのファイルはサンプルであり、接続がインストールされるわけではありません。

ホスト型コネクターのアドレスは https://mcp.apiosk.com/mcp のままです。ローカルのソースを変更しても、このデプロイには反映されません。Apiosk プラグイン は、Ask を優先する指示とホスト型接続の定義を提供します。server.json、manifest.json、dxt.json は正式なパッケージを記述するものです。デスクトップマニフェストは、ビルド済みまたはインストール済みのバンドルではありません。

設定とバックエンドの境界

変数	意味
APIOSK_GATEWAY_V2_URL	データ／実行ゲートウェイです。既定値は https://gateway.apiosk.com です。ループバック HTTP はローカルゲートウェイにのみ使用してください。
APIOSK_GATEWAY_URL	既存の OAuth エージェントゲートウェイ設定です。データ／実行ゲートウェイは選択しません。
APIOSK_CONNECT_TOKEN	stdio 用の Apiosk エージェント接続資格情報です。
APIOSK_TOKEN	接続トークンを上書きします。有効な個人用 App セッション JWT を使用すると、アカウント専用ルートが有効になります。このサーバーはその App セッションを更新しません。
APIOSK_WORKSPACE_ID	stdio ワークスペースです。HTTP 呼び出し元は x-apiosk-workspace-id を使用します。
APIOSK_MCP_STATE_DIR	永続的なプライベートジャーナルディレクトリです。既定値はパッケージ内の .local/state です。
APIOSK_MCP_PORT / PORT	HTTP ポートです。既定値は 3000 です。
APIOSK_MCP_HOST / APIOSK_MCP_BIND_HOST	リスナーのアドレスです。ホスト型エントリの既定値は 0.0.0.0 です。ローカルのみでアクセスする場合はループバックを使用してください。
APIOSK_MCP_ALLOWED_HOSTS、APIOSK_MCP_ALLOWED_ORIGINS	HTTP リスナーの明示的なホスト／オリジン制御です。

ゲートウェイのスコープ、予算、ワークスペース、機能に関する制限が引き続き適用されます。組織の API キーは、未加工のタスク／承認プロトコルにおけるエージェント接続トークンの代わりにはなりません。アカウント専用の統合やネイティブの定期実行には、有効な App セッションとバックエンドでの有効化が必要になる場合があります。app_only または public_api_required という応答を回避することはできません。

接続トークンでは /v2/ask/page を使用します。このエンドポイントは、Ask ページのインタープリター、検証、ソース検索を適用します。App セッションでは元の App ルートを使用します。どちらも同じソースフィルタリング、グループ化、入力値、表示通貨を使用します。接続済みの検索では、以前の公開 API による解釈の修正や追加のソース展開は行わず、App の一致結果を保持します。署名付き検索は、アカウント、接続、ワークスペースに引き続き紐付けられます。ソースの更新では保存済みの解析結果を再利用し、自動プランニングでは質問を再解析せず、表示されている検索を採用します。

定期実行を行うには、ワークフロー、スケジュール、送信先、費用上限を個別に明示的に確認する必要があります。apiosk_schedule_handoff はホストのスケジューラー向けの手順を提供し、schedule_created: false を返します。スケジュール済みジョブは作成しません。外部アプリでの操作にも、それぞれ個別に確認済みの実行が必要です。

保存状態、復旧、デプロイ

ジャーナルには、資格情報を保存せずに、プライベートな会話、証拠、承認の意図がプライベートなファイル権限で保存されます。会話は Web アプリのチャット履歴テーブルとは別に管理されます。権限のあるゲートウェイタスクは ID を指定してインポートできます。状態のスコープにはゲートウェイとワークスペースが含まれます。未加工のベアラー呼び出し元はトークンごとにスコープが設定されます。ホスト型 OAuth セッションでは、トークン更新後も検証済みの権限スコープが保持されます。

アトミック書き込みとリクエストごとのロックにより、ディスパッチ前に承認の意図が記録されます。不確実な購入がむやみに再実行されることはありません。保存済みのステータスを読み取り、返された復旧手順を使用してください。提示された合計額は、プロバイダー全体の支出上限であり、全か無かのトランザクションではありません。ローカルディスクで障害が発生した場合、金銭が動く操作は停止します。

ホスト型で運用するには、永続ジャーナルが必要です。Fly の設定では既存のアプリ ID を維持し、既存の mcp_state ボリュームが /data にマウントされていることを前提としています。共有状態と分散ロックが実装されるまでは、1 台のマシンのみを実行してください。デプロイ前に、そのボリュームをプロビジョニングして確認してください。デプロイとリリースの手順を参照してください。

リポジトリへのプッシュで実行されるのはチェックのみです。デプロイと公開は、それぞれ別の手動ワークフローです。テストでは管理されたフィクスチャを使用し、ソースデータの購入は行いません。ローカルでの成功は、本番環境での取得、メッセージの配信、スケジュールの実行、ホスト接続のインストールを証明するものではありません。