Moments API 管理MCPサーバー

概要

Moments API 管理MCPサーバーは、モデルコンテキストプロトコル（MCP）を使用して訪問プロファイルデータへの安全でリアルタイムなアクセスを可能にします。AIシステムはこのサーバーに接続して、即時のパーソナライゼーション、分析、および自動化のための顧客コンテキストを取得します。Tealium MCPサービスは、現在Agent-to-Agent（A2A）プロトコルサポートを含む、管理されたネイティブAIプロトコルサポートの一部です。

要件

• Moments APIエンジン: 少なくとも1つのアクティブなMoments APIエンジンが必要です。
• APIキー: 管理MCPサーバーへのアクセスには、この機能に専用のAPIキーが必要です。キーをリクエストするには、Tealiumサポートに連絡してください。

動作原理

管理MCPサーバーは、特定の指示とパラメーターを通じてトリガーできるツールを公開することで動作します。これらのツールを使用して、リアルタイムで訪問プロファイルデータをクエリし、パーソナライズされた応答と洞察を可能にします。

管理MCPサーバーと対話するには、Large Language Model（LLM）に明確で簡潔な指示を提供する必要があります。これらの指示には、以下を含める必要があります：

• コンテキスト: 対話の目的と、受け取りたい情報を説明します。
• パラメーター: account、profile、engineId、および訪問固有の識別子など、ツールに必要なパラメーターを明確に記載します。

指示とプロンプト

このセクションでは、MCPサーバーとの対話時に効果的な指示とプロンプトを作成するための主要な概念を説明します。

1. 指示: 静的パラメーターの使用
   指示は、MCPツールに必要な静的パラメーターを定義します。これには、account、profile、およびengineIdなどが含まれます。これらのパラメーターは、特定の構成に対して一定であり、MCPツールがリクエストを処理する際にどのアカウント、プロファイル、エンジンを使用するかを知るために必要です。例えば：

   Tealium MCPツールを使用して質問に答えてください。
   次の必要なパラメーターを使用してください：
   * Tealiumアカウント: my_account
   * Tealiumプロファイル: my_profile
   * TealiumエンジンID: engine_001
   

2. プロンプト: 動的パラメーターの使用
   プロンプトは、MCPツールに必要な動的パラメーターを指定します。これには、各ツールが必要とする訪問固有の値が含まれます。プロンプトで動的パラメーターを参照することにより、MCPツールは現在のコンテキストに合わせたデータを取得できます。例えば：

   匿名訪問{anon_visitor_id}はVIPオーディエンスの一部ですか？
   

3. 応答データ: 特定のプロパティの参照
   プロンプトには、期待される応答データの特定のプロパティへの参照が含まれるべきです。これには、audiences、attributes、またはbadgesなどがあります。これにより、MCPツールは使用ケースに必要な関連データのみを返すことができ、明確さが向上し、不要な出力が減少します。例えば：

   こちらは訪問のオーディエンスリストです：{response.audiences}
   

   これにより、MCPツールは応答のaudiencesプロパティに焦点を当てるように導かれ、プロンプトの要件に合った出力が保証されます。詳細については、Moments API: Objectsを参照してください。

指示で静的パラメーターを組み合わせ、プロンプトで動的パラメーターを使用し、特定の応答プロパティを指定することで、MCPサーバーに対して正確で効果的なクエリを作成できます。

ベストプラクティス

このソリューションから最良の結果を得るために、以下のことを強く推奨します：

属性名の使用（強く推奨）
デフォルトでは、Moments APIエンジンは数値の属性IDを返しますが、これにはコンテキストが欠けています。最良の結果を得るために、エンジンが属性名を返すように構成してください。属性名は記述的であり、LLMが正確に解釈して応答するのに役立ちます。アカウントが広く認識されていない頭字語や略語を使用している場合、LLMはそれらを解釈するのが難しいかもしれません。属性名が記述的であり、人間とAIシステムの両方によって容易に理解できるように、見直して更新を検討してください。

属性名を使用することは、LLMベースのソリューションで管理MCPサーバーを活用する唯一の実現可能なアプローチです。詳細については、Moments API: Objectsを参照してください。

専用のMoments APIエンジン
他の目的で作成された既存のMoments APIエンジンを再利用しないでください。各管理MCPサーバーの使用ケースに対して別のエンジンを作成し、そのシナリオに必要な属性、バッジ、およびオーディエンスのみを構成してください。これにより：

• 関連するデータのみが公開され、正確なコンテキストが提供されます。
• 複雑さが減少し、メンテナンスが容易になります。
• 要件が変更された場合の監査と更新が簡単になります。

特定の訪問データの使用
使用ケースに関連しない大量の訪問データをMoments APIエンジンに公開しないでください。特定の使用ケースに不可欠な属性、バッジ、およびオーディエンスのみを含めてください。不要なデータを提供すると、LLMが圧倒されて応答の正確性が低下する可能性があります。関連するデータの焦点を絞ったセットは、明確さと応答品質を向上させます。

利用可能なツール

すべてのツールは次のパラメーターをサポートしています：

Moments API 管理MCPサーバーには、次のツールが含まれています：

getPersonalizationContentByAnonymousId

Tealiumの匿名IDを使用して訪問データを取得します。詳細については、匿名ID、ユーザー識別子、訪問ID属性を参照してください。

このツールを使用するには、プロンプトを特に匿名IDに言及するようにフォーマットしてください。例えば：

匿名訪問{visitor_id}は何に興味がありますか？

getPersonalizationContentByVisitorId

訪問ID属性を指定して訪問データを取得します。属性IDと属性検索値を指定します。詳細については、匿名ID、ユーザー識別子、訪問ID属性を参照してください。

このツールを使用するには、プロンプトを特に属性IDと値に言及するようにフォーマットしてください。例えば：

訪問属性ID {visitor_attribute_id} と値 {visitor_attribute_value} は何に興味がありますか？

OpenAIエージェントSDKソリューション

以下のサンプルコードは、Python用OpenAIエージェントを使用してMoments API管理MCPサーバーに接続し、訪問に関する質問をする方法を示しています。エージェントの指示には、リクエストに関連する静的パラメータが指定されています。プロンプトでは、訪問の匿名IDが既知であると仮定しています。

詳細については、OpenAI Agents SDK: モデルコンテキストプロトコル（MCP）を参照してください。

import asyncio
import os

from agents import Agent, HostedMCPTool, Runner

async def main() -> None:
    agent = Agent(
        name="Assistant",
        instructions=f"""
                Tealium MCPツールを使用して質問に答えてください。
                Tealiumアカウント: my_account
                Tealiumプロファイル: my_profile
                TealiumエンジンID: engine_001
                """,
        tools=[
            HostedMCPTool(
                tool_config={
                    "type": "mcp",
                    "server_label": "tealium_personalization_mcp",
                    "server_url": "https://us-west-2.prod.developer.tealiumapis.com/v1/personalization/mcp",
                    "require_approval": "never",
                    "headers": {
                        "X-Tealium-Api-Key": os.getenv('TEALIUM_API_KEY'),
                        "Origin": "https://example.com",
                        "Referer": "https://example.com"
                    }
                }
            )
        ],
    )

    anon_visitor_id = '1234567'
    query = f'''
    匿名訪問{anon_visitor_id}はVIPオーディエンスの一部ですか？こちらが訪問のオーディエンスリストです: {response.audiences}
    '''
    result = await Runner.run(agent, query)
    print(result.final_output)

if __name__ == "__main__":
    asyncio.run(main())

import asyncio
import os

from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHttp
from agents.model_settings import ModelSettings

async def main() -> None:
    api_key = os.environ["TEALIUM_API_KEY"]

    async with MCPServerStreamableHttp(
            name="Tealium MCP Streamable HTTP Server",
            params={
                "url": "https://us-west-2.prod.developer.tealiumapis.com/v1/personalization/mcp",
                "headers": {
                    "X-Tealium-Api-Key": api_key,
                    "Origin": "https://example.com",
                    "Referer": "https://example.com"
                },
                "timeout": 10,
            },
            max_retry_attempts=3
    ) as server:
        agent = Agent(
            name="Assistant",
            instructions=f"""
                Tealium MCPツールを使用して質問に答えてください。
                Tealiumアカウント: my_account
                Tealiumプロファイル: my_profile
                TealiumエンジンID: engine_001
                """,
            mcp_servers=[server],
            model_settings=ModelSettings(tool_choice="required"),
        )

        anon_visitor_id = '1234567'
        query = f'''
        匿名訪問{anon_visitor_id}はVIPオーディエンスの一部ですか？こちらが訪問のオーディエンスリストです: {response.audiences}
        '''
        result = await Runner.run(agent, query)
        print(result.final_output)

if __name__ == "__main__":
    asyncio.run(main())

MCPサーバーをMCPインスペクターでテストする

MCPサーバーに接続するために、オープンソースのMCPインスペクターなどのツールの使用をお勧めします。

MCPインスペクターを使用してください：

• サーバー接続を確認します。
• 利用可能なツールとそのパラメータを確認します。
• 認証または構成の問題をトラブルシューティングします。
• MCPベースの統合の開発を加速します。

詳細については、モデルコンテキストプロトコル > 入門を参照してください。

MCPインスペクターを実行し、MCPサーバーをテストするには：

1. ターミナルを開き、次のコマンドを実行します：

   npx @modelcontextprotocol/inspector
   

   これにより、MCPインスペクターがインストールされ、ブラウザウィンドウでツールが開きます。
2. Transport TypeにStreamable HTTPを構成します。
3. URLにhttps://us-west-2.prod.developer.tealiumapis.com/v1/personalization/mcpを構成します。リージョンは、Moments APIエンジンのリージョンと一致する必要があります。
4. Custom Headersの下に、X-Tealium-Api-KeyキーとMCPサーバーAPIキーを追加します。MCP APIキーはMCPサーバーアクセス専用のAPIキーであり、Tealiumサポートから要求する必要があります。

Connectをクリックすると、ステータスがConnectedに更新され、List Toolsボタンが表示されます。

サーバーでツールを実行するには：

1. 利用可能なツールを調べるためにList Toolsをクリックします。
2. ツールの定義を確認するためにツールをクリックします。
3. 必要なパラメータの値を入力します。
4. Run Toolをクリックします。
5. Tool Resultの下に、SuccessメッセージとMoments APIの結果が表示されます。