aep

⚡ 3 行で始める

claude mcp add aep \
  -e AEP_CLIENT_ID=... -e AEP_CLIENT_SECRET=... \
  -e AEP_ORG_ID=...@AdobeOrg -e AEP_SANDBOX_NAME=your-dev-sandbox \
  -- npx -y @focusgts/aep-mcp-server

あとはエージェントに依頼するだけです。

「Demographic Details フィールドグループを使ってスキーマを作成し、そのスキーマに基づくデータセットを作成してください。」 「この NDJSON ファイルを取り込み、バッチが到着したら教えてください。」 「今四半期に 2 回購入した顧客のオーディエンスを作成して、有効化してください。」 「このメールアドレスのレコードをすべて削除してください。まずドライランを実行してください。」

書き込みは依頼されるまで無効です。また、safe モードで許可されるのは、Adobe が開発用と分類したサンドボックスのみです。

これを際立たせる処理の流れ

flowchart LR
  A["📐 Compose<br/>schema from field groups"] --> B["🗂️ Create<br/>dataset"]
  B --> C["📥 Ingest<br/>batch · upload · complete"]
  C --> D["🎯 Activate<br/>segment → destination"]
  D --> E["🧹 Govern<br/>erasure · expiration · quota"]
  E -. "re-audit the tenant" .-> A

Adobe のファーストパーティゲートウェイでは、Experience Platform テナントに何があるかを確認できます。しかし、データセットの作成、バッチの取り込み、オーディエンスの有効化、消去要求の送信はできません。このサーバーなら実行でき、フェイルクローズ方式のガードによって保護されています。

🧠 仕組み

flowchart LR
  A["AI agent<br/>(Claude · Cursor · Copilot)"] -- MCP / stdio --> B["aep-mcp-server<br/>61 tools"]
  B --> W{{"write guard<br/>fail-closed"}}
  W --> C["Schema Registry · Catalog<br/>Ingestion · Lifecycle · Privacy"]
  C --> F["Your AEP sandbox<br/>platform.adobe.io"]
  B --> J["Journey Optimizer<br/>read-only"]
  J --> K["ajo campaigns"]
  B --> Q["Customer Journey Analytics<br/>read-only, no sandbox"]
  Q --> L["cja.adobe.io"]

エージェントがツールを呼び出し、サーバーが OAuth Server-to-Server を介して Adobe のライブ API と通信します。書き込みガードは各ツールではなく HTTP クライアントに配置されているため、61 個すべてに適用され、どのツールでも適用漏れはありません。ブロックされた呼び出しが Adobe に到達することはありません。

🛡️ デフォルトで安全

3 つのモードがあります。どのモードでも読み取りは制限されません。

safe の判定方法 — サンドボックス名で判定しない理由。 本番サンドボックスにどのような名前を付けてもよく、prod という名前のサンドボックスが本番環境とは限りません。判定に使われるのは、Sandbox Management API の Adobe の type フィールドだけです。

判定できない場合は安全側に倒します。 タイプを判定できない場合 — 認証情報でサンドボックスのメタデータを読み取れない、API エラーが発生した、起動が完了していないなど — は、書き込みがブロックされます。認証情報の能力が低いことで、書き込み権限が付与されてはなりません。認識できない AEP_MODE は safe にフォールバックするため、入力ミスで本番環境への書き込みが許可されることはありません。

名前が文字どおり prod のサンドボックスは、モードの解決前に無条件で拒否されます。 そのため、AEP_MODE=production を設定しても許可されません。本当にそのサンドボックスの名前が prod である場合に限り、AEP_I_UNDERSTAND_THIS_WRITES_TO_PROD=true で上書きできます。推測の扱いは意図的に非対称です。名前を根拠に書き込みを許可するのは安全ではありませんが、名前を根拠に書き込みを拒否するのは安全です。最悪の場合でも、意図して上書きできる拒否にとどまるためです。

AEP_ALLOW_MUTATIONS=true が設定されていない限り、変更操作は完全に無効です。 これは意図的に AEP_MODE とは別になっています。書き込みモードを選ぶことが、「データの変更を許可する」ことにもなるべきではありません。

起動時には、常に有効なモードが表示されます。

SAFE MODE — sandbox is a development sandbox, so writes are ENABLED.
SAFE MODE — sandbox is PRODUCTION, so writes are BLOCKED. Reads work normally.
SAFE MODE — sandbox type could not be confirmed, so writes are BLOCKED (fail-closed).
READ-ONLY MODE — no write, update, or delete will be performed in any sandbox.
PRODUCTION MODE — writes permitted against ANY sandbox, including production.

ツールごとの確認ゲート

書き込み操作に一律のゲートを設けているわけではありません。一律にゲートを設けると、エージェントが役に立たなくなるためです。ゲートは、取り消し不能で影響範囲の広い操作に設けられており、いずれもネットワーク呼び出しの前に確認されます。

確認文には対象が明記されます。 データセット ID を含むフレーズは、レコード削除の場合は ID のハッシュも含むため、ある呼び出しの確認文を別の呼び出しに流用できません。汎用的な "I understand this is irreversible" では、一度入力するとあらゆる削除が承認されてしまいます。

ID 値がプロセスの外に出ることはありません。 aep_create_record_delete が返すのは件数、名前空間名、ダイジェストのみで、渡されたメールアドレスやデバイス ID は返しません。レコード削除のリクエストには、本質的に実在する人物のリストが含まれます。それらをそのまま返すツールは、触れるすべてのトランスクリプトやログの保存先に情報をコピーすることになります。

バッチの作成とファイルのアップロードにゲートを設けていないのは意図的です。これらの書き込みは追加型で、復旧可能だからです。不要なバッチは未完了のままにでき、取り込まれたデータは Data Hygiene ツールで削除できます。

ツールのアノテーション

すべてのツールには、readOnlyHint、destructiveHint、idempotentHint、openWorldHint の MCP アノテーションが付与されます。これらは説明の生成に使われるものと同じメタデータから導出されるため、両者に食い違いは生じません。

これらはクライアント向けのヒントであり、強制機能ではありません。強制するのは上記のガードです。ヒントの利点は、Claude Desktop のようなクライアントが destructiveHint を使い、人間に確認を求めるタイミングを判断できることです。これがないと、aep_delete_profile と aep_list_schemas は同じように見えてしまいます。破壊的な操作の一覧が完全に一致することをテストで検証しているため、9 つ目が追加される場合は、見落としではなく意図的な変更となります。

🛠️ 61 個のツール

すべて aep_ を接頭辞とし、verb_noun 形式の命名です。🔒 は状態を変更し、🔥 は破壊的な操作です。

データモデリングと取り込み

ガバナンス — プライバシー、ライフサイクル、イベントルーティング

これらで実現できるワークフロー

データをエンドツーエンドで取り込む — create_schema → create_dataset → create_batch → upload_batch_file → complete_batch → get_batch_status

オーディエンスを作成してアクティベートする — create_segment → estimate_segment_size → list_destinations → create_destination_connection → activate_segment

消去リクエストに対応する — get_profile_by_identity → create_record_delete → get_work_order_status

スケジュールに従ってデータを廃棄する — create_dataset_expiration → list_dataset_expirations → update_dataset_expiration → cancel_dataset_expiration

実際のテナントで実行した内容は、各ツールごとに docs/VALIDATION-MATRIX.md に記録されています。ドキュメント化されモック化されているものの、意図的に一度も実行していないサーフェスと、その理由も含まれます。

Adobe Journey Optimizer（2）

AJO は別の Adobe 製品であり、別途ライセンスが必要です。そのため、ajo_ プレフィックスを付けて、権限エラーがひと目でわかるようにしています。

書き込み操作を含めていないのは意図的です。ルートは存在しますが、実在の人々にメッセージを送信する製品に、検証されていない書き込み経路を導入する価値はありません。

📊 AEC-Bench — エージェントは実際に動作しますか？

この分野のすべての MCP サーバーは、ツールの数で説明されています。それが測るのは対応範囲であって、実力ではありません。404 を返すツールが50個あるより、動作するツールが10個ある方が優れています。

bench/ はエージェント型ベンチマークで、もう一つの指標を測定します。実際のタスクとライブテナントを与えたとき、エージェントはタスクを完了できるのか、それを証明できるのか、という点です。

npm run bench          # tier 1, read-only, safe on any tenant
npm run bench:write    # tier 2, creates and removes what it creates

現在：ティア1は5/5、ティア2は2/2、残留物はゼロです。 ティア3（不可逆）は定義済みですが、意図的に空にしています。対象タスクはキャンセルできず、完了まで30日かかる場合があります。ベンチマークは、それを実行する正当な理由にはなりません。

未構築のタスクでは低いスコアになると予想しています。それが意図した使い方です。

📈 カスタマージャーニー分析（10）

1つのOAuth認証情報で、3つのAdobeサービスを利用できます。 AEP_CLIENT_ID を所有する同じDeveloper ConsoleプロジェクトにCustomer Journey Analytics APIを追加すると、cja_* ツールが使えるようになります。2つ目のシークレットも、別の認証も不要です。

AEPのサンドボックスとCJAの会社は別物です

CJAクライアントは**x-sandbox-nameを送信しません。** CJAにはサンドボックスの概念がなく、これを付与しても、せいぜい意味がなく、トレースを誤解させるだけです。

会社の検出と、機能しない場合がある理由

Adobeがドキュメントで案内している検出エンドポイントは、GET https://analytics.adobe.io/discovery/meです。このホストはAdobe Analyticsに属しており、CJAとは別の製品です。 CJAの権限はあるもののAnalyticsの権限がない認証情報では、ここで403003 Api Key is invalidが返されます。キーに問題があるのではなく、Analyticsの権限がないだけです。CJAには独自の検出機能がありません。

実際には、これによって何かが妨げられることはありません。CJAはx-gw-ims-org-idだけで、あらゆるリソースに応答するため、会社IDは省略可能です。

# Optional. Omit it and CJA scopes by IMS org, which is what works by default.
CJA_GLOBAL_COMPANY_ID=your-global-company-id

cja_list_companiesは、現在どのコンテキストが使われているか、検出に到達できるかを報告します。検出によって複数の会社が返され、オーバーライドも設定されていない場合は、どれかを選ぶことを拒否します。黙って最初の会社を選ぶと、その後のすべてのレポートが誤った会社を参照してしまいます。

プローブとライブテストの実行

node scripts/probe-cja.mjs --env .env          # read-only, sanitized output
CJA_LIVE_TESTS=1 npm test -- tests/integration/cja-live.test.ts

ライブテストは**CJA_LIVE_TESTS=1の場合を除いてスキップされる**ため、npm testは外部環境に依存せずに実行できます。テストは読み取り専用で、認証情報やAdobeの応答全体を出力することはありません。

現時点の制限事項について

• 変更ツールはありません。 この機能は意図的に読み取り専用です。
• 上記のとおり、CJAのみの認証情報では検出を利用できません。ツールの不具合ではありません。
• cja_get_connectionは検証されていません — 検証用テナントには接続が1つもなく、テストを通すためにIDを捏造することはありません。
• ディメンションとメトリックのページングは機能しません。 CJAはこれらをページング可能に見えるcontentエンベロープでラップしますが、limitとpageは無視されます。実環境で確認したところ、いずれの場合も全38件のディメンションが返されました。search、limit、offsetはクライアント側で適用され、その旨が出力に示されます。

🥊 Adobe のファーストパーティ Experience Platform ツールとの比較

Adobe は CX Coworker Gateway を通じてファーストパーティツールを提供しています。これは本当に優れた製品です。テナントについて質問するだけであれば、こちらをお使いください。

Journey Optimizer と CJA について： Adobe はどちらにも別個のファーストパーティ MCP サーバーを提供しているため、上の表では意図的に「対象外」と記載していません。そのように記載すると誤りになるためです。このサーバーが追加で提供するのは、3 つすべてに対応する単一の認証情報と、Adobe のゲートウェイでは利用できない AEP 側の書き込み経路です。ここにある AJO と CJA のツールは読み取り専用です。

オーディエンスと宛先も利用できますが、同じゲートウェイ上の別個の Real-Time CDP ツールセットに含まれています。また Adobe は、オーディエンス、宛先、データフローの作成、アクティブ化、更新、削除はいずれもサポートされないと明言しています。読み取り専用という制限は、ゲートウェイ全体に適用されます。

両者は競合するものではなく、補完し合うものです。管理された読み取りには Adobe のゲートウェイを使い、書き込みにはこのサーバーを組み合わせてください。

Adobe の数値は、Experience Platform ツールのページ（最終更新日：2026 年 7 月 17 日）から確認しました。search_datasets、search_class_relations、search_data_access、search_data_lake、search_dule、search_query_service、search_audit、search_allowed_ip_ranges が含まれています。これはベータ版の機能であり、変更される可能性があるため、現在の数値はドキュメントでご確認ください。長期的に変わらない違いは数ではなく、読み取りと書き込みの分担です。

🔌 ツールに追加する

claude mcp add aep \
  -e AEP_CLIENT_ID=... -e AEP_CLIENT_SECRET=... \
  -e AEP_ORG_ID=...@AdobeOrg -e AEP_SANDBOX_NAME=your-dev-sandbox \
  -- npx -y @focusgts/aep-mcp-server

{
  "mcpServers": {
    "aep": {
      "command": "npx",
      "args": ["-y", "@focusgts/aep-mcp-server"],
      "env": {
        "AEP_CLIENT_ID": "...",
        "AEP_CLIENT_SECRET": "...",
        "AEP_ORG_ID": "...@AdobeOrg",
        "AEP_SANDBOX_NAME": "your-dev-sandbox"
      }
    }
  }
}

{
  "mcpServers": {
    "aep": {
      "command": "npx",
      "args": ["-y", "@focusgts/aep-mcp-server"],
      "env": {
        "AEP_CLIENT_ID": "...",
        "AEP_CLIENT_SECRET": "...",
        "AEP_ORG_ID": "...@AdobeOrg",
        "AEP_SANDBOX_NAME": "your-dev-sandbox"
      }
    }
  }
}

{
  "servers": {
    "aep": {
      "command": "npx",
      "args": ["-y", "@focusgts/aep-mcp-server"],
      "env": {
        "AEP_CLIENT_ID": "...",
        "AEP_CLIENT_SECRET": "...",
        "AEP_ORG_ID": "...@AdobeOrg",
        "AEP_SANDBOX_NAME": "your-dev-sandbox"
      }
    }
  }
}

🔐 認証情報

developer.adobe.com/consoleで取得します。プロジェクトを作成 → Experience Platform APIを追加 → OAuth Server-to-Serverを選択します。

AEP_SANDBOX_NAMEにデフォルト値がないのは意図的です。 以前はprodにフォールバックしていたため、設定ファイルで1行が欠けていると、警告なしに読み取りも含むすべてのリクエストが本番環境に送られていました。安全なデフォルト値はありません。誤った推測は、間違った環境で読み取りや書き込みが行われるまで、正しい設定と区別できないためです。明示的にprodを設定することは可能です。これは明確で意図的な選択であり、その場合も書き込みガードによって変更操作は拒否されます。

サンドボックスのスコープ設定。 すべてのツールはx-sandbox-nameを送信し、Query Service はデータベースを<AEP_SANDBOX_NAME>:allとして導出します。

🧾 利用資格

Adobe のすべての組織がすべての AEP 製品のライセンスを持っているわけではありません。ツールがAEP_403を返す場合、通常は認証情報の不備ではなく、利用資格の不足を意味します。

🏗️ アーキテクチャ

TypeScript のstrictをエンドツーエンドで適用し、@modelcontextprotocol/sdkとzod、stdio トランスポートを使用します。リクエストごとにステートレスです。

flowchart LR
  C["MCP client<br/>Claude · Cursor<br/>Copilot · ChatGPT"]
  T["aep-mcp-server<br/><b>61 tools</b><br/>14 categories"]
  G{{"write guard<br/>fail-closed"}}
  A1["Schema Registry<br/>· Catalog"]
  A2["Batch Ingestion"]
  A3["UPS · Segmentation<br/>· Destinations"]
  A4["Data Lifecycle<br/>· Privacy"]
  IMS[/"Adobe IMS<br/>OAuth S2S"/]

  C -- "stdio · JSON-RPC 2.0" --> T
  T -- "every call, no exceptions" --> G
  IMS -. "token cache · 401 re-auth" .-> T
  G -- "HTTPS · Bearer · x-sandbox-name" --> A1
  G --> A2
  G --> A3
  G --> A4

重複排除されたトークンキャッシュを使用する OAuth Server-to-Server、PII をマスキングする構造化 Pino ロギング、指数バックオフによる再試行、自動的な401再認証、動作するカーソルページネーション、構造化されたAEP_{status}エラーコード、グレースフルシャットダウンのライフサイクルを備えています。すべてのログはstderrに出力されます — stdout は MCP JSON-RPC ストリーム用に予約されています。

🧪 開発

git clone https://github.com/Focus-GTS/aep-mcp-server.git
cd aep-mcp-server && npm install && npm run build && npm test

npm run dev          # tsx src/server.ts (hot-reload)
npm test             # vitest — 509 tests
npm run typecheck    # tsc --noEmit
npm run tools        # print the registered tool surface

npm run test:liveは、実際の IMS 組織とサンドボックスに対して読み取り専用のスモークテストを実行し、認証情報、利用資格、サンドボックスのスコープ設定をエンドツーエンドで検証します。破壊的なツールは一切呼び出さず、AEP_SANDBOX_NAMEが本番以外のサンドボックスを指している必要があります。

🧩 Focus GTS Adobe スイートの一部