MCPサーバーのツールコールデータを送信するためのSDKをインストールする(クローズドベータ)

最終更新日:

Python、TypeScript、Java、または.NETで構築されたModel Context Protocol(MCP)サーバーを運用している場合、Pendo Web SDKを必要とせずに、バックエンドから直接サーバーのツールコールをエージェントアナリティクスに送信するPendo SDKをインストールできます。この記事では、各言語でのインストールとセットアップ方法、およびデータがPendoに届いていることを確認する方法について説明します。

この設定では、MCPのアクティビティ(AIクライアントがサーバー上で呼び出すツールと、各呼び出しの背後にある意図)のみを記録します。構築したAIエージェントや、ツールが行う大規模言語モデル(LLM)の呼び出しは計測されません。AIエージェントから会話データやトレースデータを送信する場合は、エージェントアナリティクスデータをPendoに送信するを参照してください。

注:MCPアナリティクスはクローズドベータ版です。アクセスをリクエストするには、Pendoのアカウント担当者にお問い合わせください。

AIコーディングアシスタントにこのセットアップを代行させるには、MCPエージェントアナリティクスセットアップスキルを使用します。詳細については、Pendo AIスキルの概要を参照してください。

前提条件

開始する前に、次のものを用意してください。

  • Pythonでmcpパッケージを使用して構築されたMCPサーバー、TypeScriptで構築されたMCPサーバー、直接、またはSpring AI経由(MCP Java SDK)を使用してJavaで構築されたMCPサーバー、またはModelContextProtocol C# SDKを使用して.NETで構築されたMCPサーバー。
  • MCPサーバー用にPendoに追加されたAIエージェント。設定手順については、PendoでAIエージェントを追加して設定するを参照してください。
  • アプリのパブリックアプリID。サブスクリプション管理者は、該当するアプリを開いた後、[設定(Settings)]>[サブスクリプション設定(Subscription settings)]>[アプリ(Applications)]でこれを確認できます。
  • エージェントID。これを確認するには、[プロダクト(Product)]>[エージェントアナリティクス(Agent Analytics)]に移動し、エージェント名の横にある設定アイコンを選択します。

デフォルトでは、SDKはhttps://app.pendo.ioにデータを送信します。サブスクリプションが別のリージョンにある場合のみ、別のエンドポイントを設定してください。PythonおよびTypeScriptではendpoint、Javaでは.endpoint()、.NETではoptions.Endpointを使用します。

PythonでMCPサーバーを設定する

Python SDKは、FastMCP、MCPServer、および低レベルのServerを含む、mcpパッケージ上に構築されたサーバーで動作します。Python 3.10以降が必要です。これはPythonのAIエージェントを計測するのと同じpendo-server-sdkパッケージであり、そのmcpエクストラとともにインストールします。

Python SDKをインストールする

mcpエクストラを含めてSDKをインストールするには、次を実行します。

pip install "pendo-server-sdk[mcp]"

requirements.txtでバージョンを固定するには、pendo-server-sdk[mcp]>=0.22.0を追加します。このエクストラはmcpパッケージをインストールします。プロジェクトですでにmcpのバージョン1.0以降が依存関係として記載されている場合は、エクストラなしでpendo-server-sdkをインストールしてください。

Python SDKをサーバーに追加する

サーバーの起動時にPendoMCPServerを作成し、サーバーインスタンスを渡します。これはツールを登録する前でも後でも作成できます。

from mcp.server.fastmcp import FastMCP
from pendo_sdk.mcp import PendoMCPServer

mcp = FastMCP("my-server")

PendoMCPServer(
    server=mcp,
    api_key="your-pendo-app-id",
    agent_id="your-agent-id",
)

@mcp.tool()
def get_tickets(status: str = "open") -> str:
    """Retrieve support tickets filtered by status."""
    ...

if __name__ == "__main__":
    mcp.run(transport="stdio")

パブリックアプリIDとエージェントIDをコードで設定する代わりに、環境変数PENDO_API_KEYとPENDO_AGENT_IDを設定することもできます。コードで設定された値が優先されます。いずれかの値が指定されていない場合、SDKは何も送信せず、警告を1件ログに記録します。どちらの方法でも、ツールの動作は変わりません。コードを変更せずにSDKを無効にするには、PENDO_DISABLED=trueを設定します。

サーバーの停止時にまだ送信待ちのイベントを配信するには、サーバーの実行ループが終了した後にpendo_sdk.flush()またはpendo_sdk.shutdown()を呼び出します。

Pythonで訪問者とアカウントを識別する

サーバーでStreamable HTTPまたはSSEを使用している場合は、受信した各リクエストから訪問者とアカウントを読み取る関数を渡すことで、各ツールコールを、それを行った訪問者とアカウントに関連付けることができます。

PendoMCPServer(
    server=mcp,
    api_key=api_key,
    agent_id=agent_id,
    visitor_id=lambda req: req.headers.get("X-User-Id"),
    account_id=lambda req: req.headers.get("X-Account-Id"),
)

stdioサーバーには読み取るリクエストがないため、代わりにvisitor_idとaccount_idに固定値を渡してください。

TypeScriptでMCPサーバーを設定する

TypeScript SDKは、TypeScriptのAIエージェントを計測するのと同じpendo-server-sdkパッケージです。MCPサーバーはそのinitMcp()関数を使用します。この関数はバージョン0.9.20以降で利用できます。

TypeScript SDKをインストールする

SDKをインストールするには、次を実行します。

npm install pendo-server-sdk

TypeScript SDKをサーバーに追加する

サーバーの起動時にinitMcp()を呼び出し、サーバーインスタンスを渡します。これはツールを登録する前でも後でも呼び出せます。

import { initMcp } from "pendo-server-sdk";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

const server = new McpServer({
  name: "my-server",
  version: "1.0.0",
});

initMcp({
  server,
  apiKey: "your-pendo-app-id",
  agentId: "your-agent-id",
});

server.registerTool(/* ... */);

0.9.20より前のバージョンでは、代わりにnew PendoMCPServer({ server, apiKey, agentId })を使用してください。

TypeScriptで訪問者とアカウントを識別する

サーバーでStreamable HTTPを使用している場合は、受信した各リクエストから訪問者とアカウントを読み取る関数を渡すことで、各ツールコールを、それを行った訪問者とアカウントに関連付けることができます。

initMcp({
  server,
  apiKey,
  agentId,
  visitorId: (ctx) =>
    ctx?.requestInfo?.headers?.["x-user-id"] ?? null,
  accountId: (ctx) =>
    ctx?.requestInfo?.headers?.["x-account-id"] ?? null,
});

stdioサーバーでは、これらの関数はnullを受け取るため、代わりにvisitorIdとaccountIdに固定値を渡してください。

JavaでMCPサーバーを設定する

Java SDKは、MCP Java SDKで登録したツールをラップします。JDK 17以降が必要です。これはMaven CentralではなくPendoのMavenリポジトリに公開されているため、ビルドには依存関係に加えてリポジトリのエントリも必要です。

Java SDKをインストールする

リポジトリと依存関係をpom.xmlに追加します。

<repositories>
  <repository>
    <id>pendo-sdk-release</id>
    <url>https://pendo.jfrog.io/artifactory/pendo-sdk-release</url>
    <snapshots><enabled>false</enabled></snapshots>
  </repository>
</repositories>

<dependency>
  <groupId>io.pendo</groupId>
  <artifactId>pendo-sdk-mcp</artifactId>
  <version>VERSION</version>
</dependency>

Gradleを使用している場合は、代わりに次の内容をビルドファイルに追加します。

repositories {
    mavenCentral()
    exclusiveContent {
        forRepository { maven { url = uri("https://pendo.jfrog.io/artifactory/pendo-sdk-release") } }
        filter { includeGroup("io.pendo") }
    }
}

dependencies {
    implementation("io.pendo:pendo-sdk-mcp:VERSION")
}

VERSIONは、インストールするリリース(例:0.23.0)に置き換えます。次に、サーバーに合ったアーティファクトを選択します。

  • pendo-sdk-mcp:MCP Java SDKのバージョン1.0以降を使用しているサーバーの場合。
  • pendo-sdk-mcp-0x:MCP Java SDKのバージョン0.18.xを使用しているサーバーの場合。
  • pendo-sdk-spring-ai:Spring AI 2.xアプリケーションの場合、またはpendo-sdk-spring-ai-0x:Spring AI 1.1以降の場合。Spring AIスターターは、アプリケーションが公開するすべてのツールを計測するため、次のセクションのコードを追加する必要はありません。パブリックアプリIDとエージェントIDは、application.properties内にpendo.api-keyとpendo.agent-idとして設定するか、環境変数PENDO_API_KEYとPENDO_AGENT_IDとして設定します。

サーバーが使用しているMCP Java SDKのバージョンがわからない場合は、mvn dependency:tree -Dincludes=io.modelcontextprotocol.sdkを実行してください。

Java SDKをサーバーに追加する

プロセスごとに1つのPendoMcpServerを作成し、サーバーを構築する際にツール仕様をwrapAll()に渡します。SDKはラップしたツールのみを記録するため、後から登録するツールはserver.addTool(pendo.wrap(spec))でラップしてください。

import io.pendo.sdk.PendoConfig;
import io.pendo.sdk.mcp.PendoMcpServer;

PendoMcpServer pendo = PendoMcpServer.create(PendoConfig.builder()
        .apiKey("your-pendo-app-id")
        .agentId("your-agent-id")
        .build());

McpSyncServer server = McpServer.sync(transportProvider)
        .serverInfo("my-server", "1.0.0")
        .capabilities(ServerCapabilities.builder().tools(true).build())
        .tools(pendo.wrapAll(searchTool(), bookingTool()))
        .build();

Javaで訪問者とアカウントを識別する

サーバーでStreamable HTTPを使用している場合は、設定にリゾルバーを追加することで、各ツールコールを、それを行った訪問者とアカウントに関連付けることができます。リゾルバーはツールコールごとに1回実行され、ヘッダーや認証済みユーザーなど、トランスポートが保存した値を読み取ります。

PendoConfig.builder()
        .apiKey(apiKey)
        .agentId(agentId)
        .visitorIdResolver(ctx -> (String) ctx.transportAttribute("user-id"))
        .accountIdResolver(ctx -> (String) ctx.transportAttribute("tenant"))
        .build();

stdioサーバーには読み取るリクエストがないため、代わりに.visitorId()と.accountId()で固定値を設定してください。訪問者が設定されていない場合、SDKは訪問者を匿名として記録し、警告を1回ログに記録します。

.NETでMCPサーバーを設定する

.NET SDKは、ModelContextProtocol C# SDKのバージョン2.3.0以降で構築されたサーバーで動作します。これはnuget.orgではなくPendoのNuGetフィードに公開されているため、パッケージを追加する前に、このフィードをパッケージソースとして追加する必要があります。

.NET SDKをインストールする

フィードを追加してパッケージをインストールするには、次を実行します。

dotnet nuget add source "https://pendo.jfrog.io/artifactory/api/nuget/v3/pendo-sdk-nuget-release/index.json" --name pendo
dotnet add package Pendo.AgentAnalytics.Mcp

プロジェクトをビルドするすべてのマシンでこのフィードを利用できるようにするには、代わりにソリューションと同じ場所にあるnuget.configファイルに追加します。

<configuration>
  <packageSources>
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
    <add key="pendo" value="https://pendo.jfrog.io/artifactory/api/nuget/v3/pendo-sdk-nuget-release/index.json" />
  </packageSources>
</configuration>

.NET SDKをサーバーに追加する

MCPサーバービルダーでWithPendoAgentAnalytics()を呼び出します。ツールを登録する前でも後でも呼び出すことができます。

using Pendo.AgentAnalytics.Mcp;

var builder = Host.CreateApplicationBuilder(args);

builder.Services
    .AddMcpServer()
    .WithStdioServerTransport()
    .WithToolsFromAssembly()
    .WithPendoAgentAnalytics(options =>
    {
        options.ApiKey = "your-pendo-app-id";
        options.AgentId = "your-agent-id";
    });

await builder.Build().RunAsync();

SDKは、設定されていないオプションを環境変数から読み取るため、引数なしでWithPendoAgentAnalytics()を呼び出すこともできます。

環境変数 設定内容
PENDO_API_KEY パブリックアプリIDです。
PENDO_AGENT_ID エージェントIDです。
PENDO_ENDPOINT SDKがデータの送信先として使用するアドレスです。デフォルトはhttps://app.pendo.ioです。
PENDO_VISITOR_ID すべてのツールコールに使用する固定の訪問者IDです。
PENDO_ACCOUNT_ID すべてのツールコールに使用する固定のアカウントIDです。
PENDO_DISABLED SDKを無効にするには、trueまたは1に設定します。

パブリックアプリIDまたはエージェントIDが設定されていない場合、SDKは何も送信せず、不足している値を示す警告をログに記録します。どちらの場合も、ツールの動作は変わりません。

.NETで訪問者とアカウントを識別する

サーバーでStreamable HTTPを使用している場合は、リゾルバーを追加して、各ツールコールを呼び出し元の訪問者とアカウントに関連付けます。リゾルバーはツールコールごとに1回実行され、認証された呼び出し元を読み取ることができます。

.WithPendoAgentAnalytics(options =>
{
    options.VisitorIdResolver = ctx => ctx.User?.FindFirst("sub")?.Value;
    options.AccountIdResolver = ctx => ctx.User?.FindFirst("tenant")?.Value;
});

stdioサーバーには読み取るリクエストがないため、options.VisitorIdとoptions.AccountId、または上記の環境変数を使用して固定値を設定します。訪問者が設定されていない場合、SDKはその訪問者を匿名として記録し、警告をログに記録します。

SDKがサーバーに加える変更

設定が完了すると、SDKは各ツールコールを記録してPendoに送信します。ツールが呼び出された理由を取得するため、SDKはサーバーがリストするすべてのツールにuser_intentパラメーターを追加し、ツールが実行される前にそのパラメーターを削除するため、ツールのコードは変更されません。また、サーバーにない機能のリクエストを記録するget_additional_toolsツールも追加します。

テストでサーバーが返すツールやパラメーターの正確な一覧を確認している場合は、これらの追加分を考慮するようにテストを更新してください。

SDKは、Streamable HTTPクライアントが送信するMCPセッションIDに基づいて、ツールコールを会話にグループ化します。stdioサーバーにはセッションがないため、SDKはそのツールコールをセッション単位でグループ化できません。

セットアップを確認する

SDKをセットアップしたら、開発環境またはステージング環境でサーバーを実行し、MCPクライアントからいずれかのツールを呼び出します。その後、サーバーログを確認します。

  • PythonとTypeScript。SDKはデータを配信するたびに1行をログに記録します。例:Exported 8 event(s) to https://app.pendo.io/data/agenticsdk/<apiKey> [200, attempt 1]。Python SDKはloggingモジュールを通じてINFOレベルでログを記録しますが、これはPythonではデフォルトで非表示になっています。これらの行を表示するには、サーバーを起動する前にlogging.basicConfig(level=logging.INFO, stream=sys.stderr)を追加してください。
  • Javaと.NET。SDKはデータの配信時には何もログに記録せず、配信が失敗したときに警告をログに記録します。Javaではpendo:で始まる警告を、.NETではPendo.AgentAnalyticsカテゴリからの警告を確認してください。

会話データは1時間ごとのバッチで処理されます。コードが本番環境で稼働した後、通常は次のバッチの開始から15分以内に新しいデータが表示されます。[プロダクト] > [エージェントアナリティクス]に移動し、エージェントを選択して、ツールコールが表示されることを確認します。

トラブルシューティング

Pendoにデータが表示されない場合は、次の確認事項を順番に確認してください。

確認事項 確認内容
ビルド時にパッケージが見つからない(Java、.NET) 依存関係を解決するビルドでPendoのリポジトリまたはフィードが設定されていないか、ネットワークがpendo.jfrog.ioをブロックしています。
ログに配信の行がない(Python、TypeScript) Pythonの場合は、セットアップを確認するの説明に従ってINFOログを有効にします。サーバーがリクエストの処理を開始する前にSDKをセットアップしていること、およびMCPクライアントからツールを呼び出していることを確認してください。PythonからFastMCP自体のlist_tools()やcall_tool()メソッドを呼び出すと、SDKがバイパスされます。
起動時に、SDKが無効であるという警告が表示される パブリックアプリIDまたはエージェントIDが見つからないか、PENDO_DISABLEDが設定されています。コード内、またはPENDO_API_KEYとPENDO_AGENT_IDの環境変数の両方に値を設定し、PENDO_DISABLEDを削除してください。
エージェントIDが不足しているか正しくない エージェントIDは必須であり、パブリックアプリIDと同じアプリ内のエージェントと一致している必要があります。Pendoは認識できないエージェントIDを含むイベントも受け付けますが、それらは表示されません。
パブリックアプリIDまたはエンドポイントが正しくない HTTP 401を伴う配信警告は、Pendoがキーを拒否したことを意味します。値がPendoのパブリックアプリIDと一致していること、エンドポイントがリージョンと一致していること、そのエンドポイントへの送信トラフィックが許可されていることを確認してください。
ツールがuser_intentパラメーターを受け取る SDKは、ツールが実行される前にこのパラメーターを削除します。それでもツールがこのパラメーターを受け取る場合は、ツールがSDKに渡したサーバーインスタンスに登録されていることを確認してください。
ツールコールが無効な引数として拒否される(Java) MCP Java SDKのバージョン1.0以降はツールの引数を検証するため、user_intentを送信しないクライアントは拒否されます。AIクライアントはこれを自動的に送信します。送信しないクライアントを受け入れるには、サーバービルダーで.validateToolInputs(false)を呼び出してください。
起動時にNoSuchMethodErrorまたはClassNotFoundExceptionが発生する アーティファクトが使用しているMCP Java SDKのバージョンと一致していません。1.0以降ではpendo-sdk-mcpを、0.18.xではpendo-sdk-mcp-0xを使用してください。
stdioサーバーでクライアントが破損したストリームを報告する 何らかの処理が標準出力に書き込みを行っていますが、stdioサーバーはこれをMCPプロトコル用に予約しています。SDKのログを含むすべてのログを、標準エラー出力またはファイルに送信してください。Pythonではprint()を呼び出さないようにしてください。TypeScriptでは、サーバーを作成する前にconsole.log = console.errorを設定してください。
ツールコールが1つの会話にグループ化されない MCPクライアントがセッションIDを送信していないか、サーバーがstdioを使用しています。
この記事は役に立ちましたか?
0人中0人がこの記事が役に立ったと言っています