affset

affset MCP サーバー

メディアバイヤーがチャットクライアントから affset を利用できる MCP サーバーです。統計情報の取得、キャンペーン・ゾーン・チームの管理、支払い、ターゲティング、サブラベルの設定、成果の低いゾーンの停止を、ダッシュボードを使わず自然な言葉で行えます。

ツールは既存の affset テナント API を利用します。ホスト型エンドポイント（OAuth、API キー不要）に接続するか、このパッケージをローカルで実行してください（Bearer トークンと X-Namespace が必要です）。1つの接続で利用できるのは1つのテナントです。

最も手軽な接続方法 — ホスト型エンドポイント。 Claude（ウェブ版またはデスクトップ版）、Cursor、Claude Code、または OAuth 対応のストリーミング可能な HTTP をサポートするクライアントで、リモート MCP サーバーとして https://mcp.affset.com/mcp を追加します。URL を貼り付け、affset のメールアドレスでサインインし、Read-only（同意画面のデフォルト）を維持するか、フルアクセスを許可してください。接続はすべてダッシュボードの「Integrations」ページに表示され、個別に取り消せます。セットアップガイド： affset.com/integrations。

以下の npm パッケージはセルフホスト用です。同じツール構成を備え、お客様自身で管理する API キーを使って、ご利用のマシン上で実行できます。AFFSET_READ_ONLY=true を設定しない場合、stdio はデフォルトでフルアクセスになります。

ツール

ツール	機能
whoami	このサーバーが紐づいているテナントを表示します。名前空間、API ベース URL、そこから導出したダッシュボード URL、および（読み取り可能な場合）会社名／タイムゾーン／カスタム API ドメインが含まれます。読み取り専用です。
get_stats	ディメンション（日付、キャンペーン、ゾーン、国、sub1～5、広告主、パブリッシャーなど）ごとにトラフィック統計をグループ化します。advertiser_email／publisher_email フィルターで絞り込むこともできます（1 ユーザー、任意の group_by）。クリック数、コンバージョン数、CR、報酬、メディア費用、ROI を表で返します。paid_only のデフォルトは true（ダッシュボードと同じ）で、そのため CR には情報提供用コンバージョンが含まれません。sub 列には、設定されている場合、テナントの sub ラベルが使われます。ユーザーごとのグループ化とフィルターは、オーナー／マネージャーと、該当する側のマネージャーロールが対象です。
list_campaigns	キャンペーンを一覧表示します（ステータス／名前フィルター、ページネーション）。
get_campaign	1 件のキャンペーンの完全なレコードを返します。すべてのフィールド（省略されていないオファー URL、正確なスケジュール、予算／ペーシング、サイレントフラグ、報酬目標タイプ）に加え、ターゲティングルールと報酬ルールも 1 回の呼び出しで取得できます。
list_zones	トラフィックソースのゾーンを一覧表示します（ステータス／名前フィルター、ページネーション、紐づくソース）。
list_team	チームメンバーを一覧表示します（メールアドレス、ロール、マネージャー）。API トークンは決して返しません。
create_team_member	チームメンバーを招待します（owner、manager、publisher、advertiser、publisher_manager、advertiser_manager）。スコープ付きマネージャーキーで作成できるのは、自身が管理するロールのみで、作成者自身に割り当てられます。新しい API キーは一度だけ返されます。list_team では再表示されません。デフォルトではドライランです。適用するには confirm: true を指定します。
create_campaign	広告主のメールアドレス、オファー URL、地域、報酬、名前からキャンペーンを作成します。デフォルト値は CPA／レート 0、一時停止、グローバル報酬ルール、および利用可能なトラッキングリンク（設定済みの場合は紐づくソーステンプレート、それ以外の場合は source_click_id={clickid} と sub プレースホルダー）です。デフォルトではドライランです。適用するには confirm: true を指定します。
set_campaign_status	キャンペーンを実行または一時停止します（action: "run" | "pause"）。デフォルトではドライランです。適用するには confirm: true を指定します。実行すると、プランのアクティブキャンペーン数上限に達する場合があります。
update_campaign	部分更新します（名前、オファー URL、ステータス、レート、予算、日付など）。デフォルトではドライランです。適用するには confirm: true を指定します。実行／一時停止には set_campaign_status を使用してください。
create_zone	トラフィックソースのゾーンを作成します（名前と、任意のポストバック／サイト／トラフィックバック URL、任意の traffic_source_id リンク）。常に active として作成されます。デフォルトではドライランです。適用するには confirm: true を指定します。
update_zone	部分更新します（名前、ステータス、URL、traffic_source_id）。デフォルトではドライランです。適用するには confirm: true を指定します。URL を消去するか、ソースの紐づけを解除するには null を渡します。
list_traffic_sources	トラフィックソース（購入先のネットワーク）を一覧表示します。それぞれに、紐づくゾーンで使われるトラッキング／ポストバックテンプレートが含まれます。API トークンは設定済み／未設定のみ表示されます。
create_traffic_source	トラフィックソースを作成します。ネットワークプリセット（exoclick、trafficstars、propellerads、adsterra、richads）から作成すると、検証済みテンプレートが編集可能な行にコピーされます。デフォルトではドライランです。適用するには confirm: true を指定します。
update_traffic_source	部分更新します（名前、テンプレート、api_token、ステータス）。紐づくゾーンには新しいトラッキングテンプレートがすぐに反映されます。デフォルトではドライランです。適用するには confirm: true を指定します。
list_source_bids	1 つのトラフィックソースのネットワークキャンペーンと現在の入札額をネットワークアカウントからリアルタイムで読み取ります（ExoClick、TrafficStars、RichAds。ソースの API トークンが必要です）。ステータス、価格モデル、USD 建ての入札額、Affset の変更処理段階に入った直近の変更を表示します。読み取り専用です。
set_source_bid	既存の価格モデルを使って、1 つのネットワークキャンペーンの入札額を USD で設定します（RichAds の場合、ポップは CPM、プッシュ／ディスプレイは CPC）。ドライランでは expected_current_bid が返されます。この値を confirm: true とともに渡すと、確認済みの入札額に紐づけて書き込みを行います。そのため、同時変更があった場合は上書きせず拒否されます。試行はソースの入札履歴に記録され、ネットワークから新しい値が返された場合のみ適用済みと報告されます。入札額を 5 倍超に引き上げるには allow_large_increase: true が必要です。デフォルトではドライランです。
get_zone_url	ネットワークのキャンペーン設定に貼り付ける /serve URL です。ゾーンのアクティブなキャンペーンをローテーションします。トラフィックソースに紐づくゾーンでは、そのソースのトラッキングテンプレートを使って生成します。それ以外の場合は、事前入力された sub 規約と任意の cost マクロを使います。アクティブなキャンペーンが見つからない場合は警告します。
get_tracking_link	既存のキャンペーンとゾーンに対する /track/click リンクです。ローテーションやターゲティングのチェックを行わず、1 つのアクティブなキャンペーンに直接リンクします。get_zone_url と同様に、紐づくソースのテンプレートを使って生成します。create_campaign の作成時に返された内容を再導出します。
cut_zones	閾値（CR／支出／ROI）に基づき、パフォーマンスの低いゾーンをキャンペーンでブラックリストに登録します。デフォルトではドライランです。適用するには confirm: true を指定します。
list_payout_rules	キャンペーンのグローバルおよびゾーンごとの報酬ルールと payout_goal_type を一覧表示します。
set_payout_rule	グローバルまたはゾーン固有の報酬を追加または更新します。デフォルトではドライランです。適用するには confirm: true を指定します。
delete_payout_rule	グローバルまたはゾーン固有の報酬ルールを削除します。デフォルトではドライランです。適用するには confirm: true を指定します。
set_payout_goal	payout_goal_type（目標ベースのコンバージョン）を設定または解除します。デフォルトではドライランです。適用するには confirm: true を指定します。
list_targeting_types	ターゲティングルールタイプのカタログを表示し、登録済みのうち /serve で評価されないものに印を付けます。
list_targeting_rules	キャンペーンのターゲティングルールを一覧表示し、効果のないものに印を付けます。
set_targeting_rule	ターゲティングルールを 1 件追加または更新し、安全にマージしたうえで /serve が照合する形式に正規化します。デフォルトではドライランです。適用するには confirm: true を指定します。
remove_targeting_rule	ID またはタイプ＋メソッドを指定して、ターゲティングルールを 1 件削除します。デフォルトではドライランです。適用するには confirm: true を指定します。
list_sub_labels	sub1～sub5 のテナント表示名を一覧表示します。
set_sub_labels	sub ラベルを設定または解除します（部分更新。null で解除）。デフォルトではドライランです。適用するには confirm: true を指定します。
list_conversions	コンバージョン監査レコードを一覧表示します（報酬、支出、ピクセルタイプ、ペイロード、ポストバック）。paid_only はサーバー側でフィルターされ、それ以外の任意のフィルターは現在のページに対してクライアント側で適用されます。

ネットワークにはどの URL を渡せばよいですか？

	get_zone_url (/serve/{zone})	get_tracking_link (/track/click/{campaign}/{zone})
キャンペーンの選択	affset がゾーンのローテーションから選択	固定のキャンペーンを指定
有効なキャンペーンが必要	はい — そうでない場合はトラフィックが戻されるか、未販売になります	はい — そうでない場合は 404 になります
有効なゾーンが必要	はい	はい
地域およびターゲティングルール	適用される	適用されない
cost= の記録先	インプレッションの行	クリックの行

トラフィックのストリームごとにどちらか一方を使用してください。cost= を付けて両方を使用すると、 メディア費用が二重に計上されます。

テナントにカスタム API ドメインが設定されている場合、どちらもそのドメインを使用します。URL は そのままネットワークに貼り付けられるためです。マクロ（{clickid}、[CLICK_ID]、${SUBID}）は パーセントエンコードされずに挿入されます。リクエストが affset に届く前に、ソース側で展開されます。

cut_zones はキャンペーンのブラックリストにゾーンを追加するだけで、既存のターゲティングルールには 一切触れないよう、読み込み、マージ、書き込みを行います。

create_campaign でトラッキングリンクを使うには、トラフィックソースのゾーンが必要です。 zone_id を渡すか、名前空間に有効なゾーンがちょうど 1 つある場合は自動選択させてください。 キャンペーンは paused 状態で作成されます。どちらかの URL を通じてトラフィックを送る前に、 キャンペーンを有効化してください。どちらの URL タイプでも、有効なゾーンが必要です。地域の許可リストは /serve でのみ適用されます。直接トラッキングリンクには地域制限はありませんが、現在サービスを提供できる 有効なキャンペーンが引き続き必要です。

ドキュメントリソース

ツールに加えて、このサーバーは affset のAPI リファレンスを MCP リソースとして公開しています。そのため、 アシスタントはツールスキーマだけでなく、ドキュメント自体から「コンバージョントラッキングの仕組みは？」 や「/serve では何を指定できる？」といった質問に回答できます。

リソース URI	種類	内容
affset://docs/api-reference	text/markdown	API リファレンス全体 — エンドポイント、認証、ロール、例。
affset://docs/api-reference.json	application/json	同じリファレンスの構造化データ版。プログラムから利用できます。

これらは affset.com/docs で公開されている内容そのもので、単一のソースから 生成され、AFFSET_DOCS_URL（{origin}/api-reference.md および {origin}/api-reference.json）から 読み取り時に取得されます。そのため、このパッケージに固定されたコピーではなく、常に現在公開されている ドキュメントを反映します。取得時に認証情報は送信されません（ドキュメントは公開されており、 テナント API とは異なるオリジンにあります）。HTML の SPA フォールバック、リダイレクト、無効な JSON、 サイズ超過の本文は拒否されます。AFFSET_READ_ONLY の場合を含め、両方のリソースを常に利用できます。

設定

セルフホスト（stdio）のみで使用できます。ホスト型接続では、これらの変数は使用しません。設定はすべて環境変数から取得されます（ハードコードはされません）。

変数	説明
AFFSET_BASE_URL	affset API のオリジン。例：https://api.affset.com（パス、クエリ、認証情報は含めません）。ホストが localhost／127.0.0.1／::1 でない限り、https が必須です。http を使うと API キーが平文で送信されます。
AFFSET_API_KEY	テナントの API キーです。名前空間は AFFSET_NAMESPACE と一致している必要があります。
AFFSET_NAMESPACE	テナントの名前空間です（小文字、数字、ハイフン。3～63 文字。サインアップ時と同じルールです）。
AFFSET_READ_ONLY	任意。デフォルトは false です。true／1 に設定すると、読み取り専用ツール（whoami、get_stats、get_campaign、すべての list_*、get_zone_url、get_tracking_link）のみが登録されます。作成／更新／削除／カットの各ツールは、確認の背後で制限されるだけではなく、すべて使用できなくなります。この設定が重要な理由については、セキュリティをご覧ください。
AFFSET_REQUEST_TIMEOUT_MS	任意。デフォルトは 30000 です。リクエストごとの HTTP タイムアウトをミリ秒単位で指定します（1000～300000）。
AFFSET_DOCS_URL	任意。デフォルトは https://affset.com です。API リファレンスのドキュメントリソースを取得するオリジンを指定します（オリジンのみ。パスは含めません）。匿名で取得されるため、API キーは送信されません。

.env.exampleをご覧ください。

インストール

ホスト型（最速 — インストール不要）

MCP クライアントにリモートサーバーを追加し、ブラウザーでアクセスを承認してください。 OAuth はエンドポイントから検出されます。API キーを貼り付けたり、 Authorization ヘッダーを追加したりしないでください。

• Claude（ウェブまたはデスクトップ） — カスタマイズ → コネクター → + → カスタムコネクターを追加 → https://mcp.affset.com/mcp。
• Cursor — 設定 → MCP → サーバーを追加、トランスポート「streamable HTTP」、同じ URL を指定します。
• Claude Code — claude mcp add --transport http affset https://mcp.affset.com/mcp を実行し、/mcp で認証します。

affset のメールアドレスでサインインします（マジックリンク）。同意画面では、 フルアクセスに切り替えない限り、読み取り専用が選択されています。接続には 独自のスコープ付き認証情報が割り当てられるため、API キーは使用されません。また、 ダッシュボードの「連携」ページに表示され、いつでも取り消すことができます。詳しい ガイド：affset.com/integrations。

以下のセルフホスト方法では、同じツール一式を stdio 経由で実行します。 Node.js 22.13 以降が必要です。

npm からインストール（セルフホストにおすすめ）

クローンもビルドも不要です。MCP クライアントが npx で実行します。Claude Desktop （claude_desktop_config.json）の場合：

{
  "mcpServers": {
    "affset": {
      "command": "npx",
      "args": ["-y", "@affset/mcp"],
      "env": {
        "AFFSET_BASE_URL": "https://api.affset.com",
        "AFFSET_API_KEY": "sk_live_...",
        "AFFSET_NAMESPACE": "your-namespace"
      }
    }
  }
}

Claude Code の場合：

claude mcp add affset \
  -e AFFSET_BASE_URL=https://api.affset.com \
  -e AFFSET_API_KEY=sk_live_... \
  -e AFFSET_NAMESPACE=your-namespace \
  -- npx -y @affset/mcp

npm レジストリではなく GitHub からインストールする場合は、-- npx -y github:affset/mcp を指定すれば、同じ環境変数フラグを使用できます（下記参照）。

統計・レポート専用のインスタンスにするには、-e AFFSET_READ_ONLY=true を追加してください（セキュリティを参照）。

GitHub から直接インストール（npm での公開は不要）

npx は npm レジストリではなく、Git リポジトリから直接インストールできます。公開を避けたい場合や、リリース手順を経ずに main を追跡したい場合に便利です：

{
  "mcpServers": {
    "affset": {
      "command": "npx",
      "args": ["-y", "github:affset/mcp"],
      "env": {
        "AFFSET_BASE_URL": "https://api.affset.com",
        "AFFSET_API_KEY": "sk_live_...",
        "AFFSET_NAMESPACE": "your-namespace"
      }
    }
  }
}

main へのプッシュにより、この固定されていないインストール方法でそのコミットを利用できるようになります。npm での公開は不要です。依存関係の解決時に、npm はリポジトリを取得し、バイナリの起動前に prepare スクリプトを実行して dist/ をビルドします。npm は次回以降の起動時にキャッシュを再利用することがあります。実行中の MCP プロセスは、再起動して npx が依存関係を再度解決するまで更新されません。

再現可能なデプロイでは、main の最新状態を追うのではなく、レビュー済みの参照を固定してください：github:affset/mcp#<commit-sha> または github:affset/mcp#<tag>。新しいリビジョンを解決して実行するには、MCP プロセスを意図的に再起動してください。

ソースからインストール

git clone https://github.com/affset/mcp.git affset-mcp
cd affset-mcp
npm install        # builds via the prepare script

その後、ビルド済みのエントリーファイルを MCP クライアントに指定します。上記の npx コマンドを "command": "node"、"args": ["/absolute/path/to/affset-mcp/dist/index.js"] に置き換えてください。

使用例

一時停止中のキャンペーンを一覧表示 → list_campaigns(status: "paused")

キャンペーン 42 のすべての情報を表示 → get_campaign(campaign_id: 42)

ゾーンを表示 → list_zones()

チームのメンバーは誰ですか？ → list_team()

[email protected] をパブリッシャーとして追加 → create_team_member(email: "[email protected]", role: "publisher")（ドライラン）→ 確認

今日の sub1 別の統計 → get_stats(group_by: "sub1")

広告主別の統計 → get_stats(group_by: "advertiser_email")

1 人のパブリッシャーのゾーン別統計 → get_stats(group_by: "zone_id", publisher_email: "[email protected]")

参考コンバージョンを含む統計 → get_stats(paid_only: false)

RichAds を最初から最後まで設定 → create_traffic_source(name: "RichAds", preset: "richads")（ドライラン）→ 確認 → create_zone(name: "RichAds push", traffic_source_id: "…")（ドライラン）→ 確認 → get_zone_url()

オファー X、広告主 [email protected]、地域 BR、報酬 $2 でキャンペーンを作成 → create_campaign(user_email: "[email protected]", offer_url: "https://offer.example/lp?s={click_id}", geo: ["BR"], payout: 2)（ドライラン）→ 確認

RichAds に貼り付ける URL はどれですか？ → get_zone_url() — トラフィックソースにリンクされたゾーンには、そのソースのテンプレートが入力されます

キャンペーン 42 のリンクをもう一度表示 → get_tracking_link(campaign_id: 42)

キャンペーン 42 を実行 → set_campaign_status(campaign_id: 42, action: "run")（ドライラン）→ 確認

キャンペーン 42 を一時停止 → set_campaign_status(campaign_id: 42, action: "pause")（ドライラン）→ 確認

ゾーンのポストバックを設定 → update_zone(zone_id, postback_url: "…")（ドライラン）→ 確認

CR < 0.2%、消化額 > $5 のゾーンを除外 → cut_zones(campaign_id, cr_max: 0.002, spend_min: 5)（ドライラン）→ 確認

キャンペーン 42 の報酬を表示 → list_payout_rules(campaign_id: 42)

ゾーンの報酬を $3 に設定 → set_payout_rule(campaign_id: 42, payout: 3, zone_id: "…")（ドライラン）→ 確認

入金コンバージョンのみ報酬対象にする → set_payout_goal(campaign_id: 42, goal_type: "deposit")（ドライラン）→ 確認

利用可能なターゲティングタイプは何ですか？ → list_targeting_types()

キャンペーン 42 で BR+MX を許可リストに設定 → set_targeting_rule(campaign_id: 42, type: "geo", method: "whitelist", rule: "BR,MX")（ドライラン）→ 確認

sub1 を Zone、sub2 を Creative という名前にする → set_sub_labels(sub1: "Zone", sub2: "Creative")（ドライラン）→ 確認

最近のコンバージョンを表示 → list_conversions()

参考コンバージョン（目標タイプの不一致）を非表示にする → list_conversions(paid_only: true)

報酬 $0（ルールなし／このページにまだ残っているもの）を検索 → list_conversions(zero_payout: true)

ソースクリック ID で検索 → list_conversions(source_click_id: "abc123")

注意事項と制限

• get_stats は呼び出しごとに1つのディメンションでグループ化します。 ドリルダウンは一連の呼び出しで行い、それぞれ campaign_ids / zone_ids / sub1..sub5 / conversion_type / advertiser_email / publisher_email / paid_only のフィルターで絞り込みます。2つのメールフィルターを使うと、group_by を変更せずに、特定ユーザーのキャンペーンまたはゾーンを選択できます。アクセスは、オーナー／マネージャー、または該当する範囲のマネージャーロールに限定されます。conversion_type でフィルタリングするとコンバージョン行のみが返されます（インプレッション、クリック、メディア費用は0です）。paid_only のデフォルトは true です（API のデフォルトは false ですが、ダッシュボードの動作に合わせています）。これにより、postback_skipped=non_goal_type（ピクセルの type がキャンペーンの payout_goal_type と一致しなかった）として記録された参考情報となる行が除外され、コンバージョン数と CR が減少します。サイレントコンバージョンは引き続きカウントされます。これは payout>0 によるフィルターではありません。生の件数を取得するには false を設定してください。フィルタリングされるのは直近の（未集計の）イベントのみで、日次アーカイブにすでに含まれているコンバージョンは引き続き集計対象です。
• spend は media_cost（トラフィック費用）を意味します。 ROI／費用のしきい値を使うには、対象の範囲に費用データがインポートされている必要があります。
• リストエンドポイントにはサーバー側の名前検索機能がありません。name_contains は現在のページをクライアント側でフィルタリングします。
• 日付範囲のプリセット、YYYY-MM-DD の範囲指定、表示されるタイムスタンプはすべてテナントのタイムゾーン（/api/tenant から一度取得）に基づきます。そのため、期間は group_by=date が返す日付区分と一致し、2つの日付区分にまたがることはありません。明示的に指定するタイムスタンプには Z または UTC オフセットを含める必要があります。
• すべての変更操作（作成、更新、カット、削除）は、ドライランの後に confirm: true を指定する方式です。作成は確認後に追加され、書き込まれた内容が返されます。
• キャンペーンの有効化やゾーンの作成では、402 プラン上限エラーが返される場合があります。エラーにはディメンション／現在値／上限が示されます。
• コンバージョン時の支払い額の決定は、ゾーン固有 → グローバル → $0 の順です。ゴールタイプによって、ピクセルの type= との一致を条件に費用／支払い額が決まります。一致しないイベントも $0 で記録されます。支払い額は $0.00001 まで設定できるため、金額は小数点以下最大5桁で表示されます。
• 支払い額の変更は、削除してから作成する処理です。 API に更新機能はなく、（campaign, zone）の組み合わせは一意です。作成に失敗した場合、set_payout_rule は以前の支払い額を復元します。復元できない唯一のケースでは、その旨を明確に通知します。
• ターゲティングが適用されるのは /serve のみで、トラッキングリンクへの直接アクセスには適用されません。set_targeting_rule / remove_targeting_rule は安全にマージし、他のルールは保持します。
• ターゲティング値は、配信時に大文字と小文字を区別して完全一致で照合されます（地域は CF-IPCountry、OS／ブラウザーはユーザーエージェント、デバイスタイプは固定の値一覧を参照）。set_targeting_rule は可能な値を正規化し（br,mx → BR,MX、android → Android）、一致し得ない値は拒否します。一致する値がないホワイトリストを設定すると、配信は通知なしで停止します。
• /serve では capping、weekdays、hours は初期設定されていますが、評価されません。設定するとターゲティングが機能しているように見える一方でキャンペーンは購入を続けるため、set_targeting_rule はこれらの書き込みを拒否します。list_targeting_types でもその旨が示されます。頻度制限には unique_users（visits/hours）を使用してください。
• list_conversions はコンバージョンの監査証跡であり、集計統計ではありません。API にキャンペーン／ゾーン／日付のフィルターはなく、サーバー側のフィルターは paid_only のみです（true にすると postback_skipped=non_goal_type（ピクセルの type がキャンペーンの payout_goal_type と一致しなかった）として記録された行が除外されます。サイレントコンバージョンやその他のスキップ理由は引き続き返されます。これは payout>0 によるフィルターではありません）。その他の任意のフィルターは現在のページにのみ適用されます。行には campaign_id／zone_id は含まれません。パブリッシャー側のロールには spend が表示されず、広告主側のロールには payout が表示されないため、zero_payout の確認にはアクセス可能なロールが必要です。paid_only は payout ではなく postback_skipped を基準にするため、そのようなロールは不要です。
• create_team_member はダッシュボードの「Add Team Member」と同様に、API キーを直接作成します。招待メールは送信しません。返されたキーは、自分で本人に渡してください。チームメンバーの無効化／削除はまだツールでサポートされていないため、ダッシュボードの Team ページを使用してください。
• 対象外：キャンペーン／ゾーン／コンバージョンの削除、請求、クリエイティブ管理。
• テナント登録は意図的にツール化されていません。 POST /api/public/create-instance は Origin を検証し、検証に失敗した場合は処理を拒否します。これにより登録はブラウザー経由に限定されています。サーバー側の呼び出し元がこの検証を通過するには、許可リストに登録された Origin を偽装する必要があります。また、このエンドポイントはメール配信が設定されている場合、API キーを返さず、代わりにマジックリンクを送信します。このサーバーは起動時に環境変数から1つの名前空間をバインドするため、自分で作成したばかりのテナントを使用できません。ダッシュボードで登録してから、新しい名前空間を指定してサーバーインスタンスを起動してください。

ライブラリとしての使用

0.2.0 以降、このパッケージはランタイムに依存しないライブラリとしても機能します。stdio サーバーが登録するすべての要素（ツール、ドキュメントリソース、読み取り専用設定の適用）は、fetch に対応した任意のランタイム（Node ≥22.13 または Cloudflare Workers）で動作する 1 つのヘルパーとして公開されています。ホスト型の affset MCP ゲートウェイ（mcp.affset.com）もまったく同じインターフェースを使用するため、リモートのツール一覧が stdio と食い違うことはありません。

import { registerAffsetTools, type Config } from "@affset/mcp/core";

const config: Config = {
  baseUrl: "https://api.affset.com",
  docsBaseUrl: "https://affset.com",
  apiKey: perRequestKey, // e.g. an OAuth grant's backing credential
  namespace: tenantNamespace,
  requestTimeoutMs: 30_000,
  readOnly: scope === "read", // never registers tools without readOnlyHint: true
};

registerAffsetTools(server, config); // server: your own McpServer instance

registerAffsetTools は McpServer を構造的に受け取るため、お使いの @modelcontextprotocol/sdk のインストールをそのまま利用できます。このパッケージに含まれるものとバージョンを合わせる必要はありません。環境変数（AFFSET_*）の読み込みは、意図的にライブラリのインターフェースに含めていません。これは stdio のエントリーポイント専用です。3 つ目の省略可能な引数 { onToolCall } を指定すると、トランスポート側での監査ログ記録のために、ツール名、所要時間、成功／エラーのステータスのみが通知されます。引数と出力は含まれません。

ライブラリは、何かを登録する前に config を検証して正規化します。リモート API のオリジンには HTTPS が必要です（ループバックの場合に限り、通常の HTTP も使用できます）。オリジンに認証情報やパスを含めることはできません。また、無効な名前空間、タイムアウト、API キー、またはブール値以外の読み取り専用設定がある場合は、起動時に安全側に倒して失敗します。公開宣言は Node のアンビエント型に依存しないため、Workers やその他の Web 標準ランタイムでも同じインポートを型チェックできます。

開発

npm run type-check   # tsc --noEmit
npm run lint         # eslint src
npm run format       # prettier --write .
npm run build        # compile to dist/
npm test             # build + node --test over dist/**/*.test.js
npm run check-all    # lint + format:check + type-check + test — CI runs this
npm run dev          # watch mode

セキュリティ

• ホスト型（https://mcp.affset.com/mcp）： マジックリンクによる OAuth を使用します。読み取り専用が同意時のデフォルトです（変更用ツールは登録されません）。フルアクセスの場合も、confirm: true になるまで変更をドライランします。ダッシュボードの「Integrations」ページから取り消せます。mcp.affset.com／oauth.affset.com で API キーを求めることはありません。
• セルフホスト（stdio）： リポジトリにシークレットは含まれません。認証情報は実行時に環境から取得します。所有者キーを再利用するのではなく、専用の最小権限で有効期限付きの API キーを作成してください。
• AFFSET_BASE_URL は、ホストがループバックの場合を除き、https である必要があります。API キーを暗号化されていない状態で送信することはありません。
• テナント API のレスポンスは、上限を 5 MB としてストリーミングされます。これを超える本文は、解析またはモデルコンテキストへの到達前にキャンセルされます。
• stdout は JSON-RPC チャネルです。すべてのログは stderr に出力されます。
• list_team は API トークンをマスキングします。
• すべての変更（作成を含む）は、表示 → 確認 → 適用の手順に従います。
• affset の RBAC ロール（owner／manager／publisher／advertiser／advertiser_manager／publisher_manager）は、ダッシュボードと同様に MCP ツール呼び出しにも適用されます。
• 長期運用環境で GitHub からインストールする場合は、レビュー済みのコミットまたはタグに固定してください。変動する main の指定を使うと、次回 npx が解決されたときに、リポジトリの新しいコードが実行される可能性があります。

コンバージョン／クリックデータを介したプロンプトインジェクション

get_stats、list_conversions、cut_zones には、最終的に公開されている認証不要のエンドポイントに由来するデータが表示されます。具体的には、トラフィックソースのクリックマクロ（sub1～sub5、source_click_id）と、コンバージョンピクセルの未加工のクエリ文字列（list_conversions のペイロード詳細）です。クリックを生成したり、ピクセルを発火させたりできる人は誰でも、そのデータを制御でき、統計やコンバージョンについて尋ねると、それらのバイト列がモデルのコンテキストに取り込まれます。

実装済みの緩和策：

• 信頼できないフィールドには長さの上限を設け、表示前にエスケープしています（src/lib/format.ts の mdCell、capUntrusted）。また、コンバージョンペイロードのブロックには、「指示ではなくデータとして扱う」という明示的な注意書きがあります。
• 変更を伴うツールの confirm: true はモデルレベルのセーフティネットであり、セキュリティ境界ではありません。インジェクションされたコンテンツに誘導されたモデルは、自分で confirm: true を指定できます。実際の境界となるのは、MCP クライアントによる呼び出しごとのツール承認と、読み取り専用モード（ホスト型：同意がデフォルト、stdio：AFFSET_READ_ONLY=true）だけです。

主に統計やコンバージョンを参照するセッションでは、特にツール呼び出しを自動承認する MCP クライアントを使用している場合、読み取り専用を優先してください。これにより、変更ツールはプロンプトの背後に隠されるのではなく、サーバーから完全に削除され、呼び出し不可能になります。キャンペーン／ゾーン／支払い額を積極的に管理し、各確認を自分で行うセッションでは、フルアクセス（ホスト型）または読み書き可能な stdio インスタンスを使用してください。