Install an SDK to send MCP server tool call data (closed beta)

Last updated:

If you run a Model Context Protocol (MCP) server built in Python, TypeScript, Java, or .NET, you can install a Pendo SDK that sends the server's tool calls to Agent Analytics directly from your backend, with no Pendo Web SDK required. This article covers installation and setup for each language, and how to verify that data is reaching Pendo.

This setup records MCP activity only: the tools AI clients call on your server and the intent behind each call. It doesn't instrument an AI agent you build or the large language model (LLM) calls your tools make. To send conversation and trace data from an AI agent instead, see Send Agent Analytics data to Pendo.

Note: MCP analytics is in closed beta. To request access, contact your Pendo account representative.

To have an AI coding assistant do this setup for you, use the MCP Agent Analytics setup skill. For more information, see Overview of Pendo AI skills.

Prerequisites

Before you begin, you must have:

  • An MCP server built in Python with the mcp package, in TypeScript, in Java with the MCP Java SDK (directly or through Spring AI), or in .NET with the ModelContextProtocol C# SDK.
  • An AI agent added in Pendo for your MCP server. For setup steps, see Add and configure AI agents in Pendo.
  • Your app's Public App ID. A subscription admin can find this in Settings > Subscription settings > Applications after opening the relevant app.
  • Your Agent ID. To find it, go to Product > Agent Analytics, then select the settings icon next to the agent name.

By default, the SDK sends data to https://app.pendo.io. Set a different endpoint only if your subscription is in another region: use endpoint in Python and TypeScript, .endpoint() in Java, or options.Endpoint in .NET.

Set up a Python MCP server

The Python SDK works with servers built on the mcp package, including FastMCP, MCPServer, and the low-level Server. It requires Python 3.10 or later. It's the same pendo-server-sdk package that instruments Python AI agents, installed with its mcp extra.

Install the Python SDK

To install the SDK with its mcp extra, run:

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

To pin it in requirements.txt, add pendo-server-sdk[mcp]>=0.22.0. The extra installs the mcp package. If your project already lists version 1.0 or later of mcp as a dependency, install pendo-server-sdk without the extra.

Add the Python SDK to your server

Create a PendoMCPServer when your server starts and pass it your server instance. You can create it before or after you register your tools.

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")

Instead of setting your Public App ID and Agent ID in code, you can set the PENDO_API_KEY and PENDO_AGENT_ID environment variables. A value set in code takes priority. If either value is missing, the SDK sends nothing and logs one warning. Your tools work the same either way. To turn the SDK off without changing your code, set PENDO_DISABLED=true.

To deliver events that are still waiting when your server stops, call pendo_sdk.flush() or pendo_sdk.shutdown() after your server's run loop returns.

Identify visitors and accounts in Python

If your server uses Streamable HTTP or SSE, pass functions that read the visitor and account from each incoming request, so each tool call is tied to the visitor and account that made it.

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"),
)

A stdio server has no request to read from, so pass fixed values for visitor_id and account_id instead.

Set up a TypeScript MCP server

The TypeScript SDK is the same pendo-server-sdk package that instruments TypeScript AI agents. MCP servers use its initMcp() function, which is available in version 0.9.20 and later.

Install the TypeScript SDK

To install the SDK, run:

npm install pendo-server-sdk

Add the TypeScript SDK to your server

Call initMcp() when your server starts and pass it your server instance. You can call it before or after you register your tools.

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(/* ... */);

In versions earlier than 0.9.20, use new PendoMCPServer({ server, apiKey, agentId }) instead.

Identify visitors and accounts in TypeScript

If your server uses Streamable HTTP, pass functions that read the visitor and account from each incoming request, so each tool call is tied to the visitor and account that made it.

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

On a stdio server, these functions receive null, so pass fixed values for visitorId and accountId instead.

Set up a Java MCP server

The Java SDK wraps the tools you register with the MCP Java SDK. It requires JDK 17 or later. It's published to Pendo's Maven repository, not Maven Central, so your build needs the repository entry as well as the dependency.

Install the Java SDK

Add the repository and the dependency to your 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>

If you use Gradle, add this to your build file instead:

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")
}

Replace VERSION with the release you want to install, for example 0.23.0. Then choose the artifact that matches your server:

  • pendo-sdk-mcp for servers on version 1.0 or later of the MCP Java SDK.
  • pendo-sdk-mcp-0x for servers on version 0.18.x of the MCP Java SDK.
  • pendo-sdk-spring-ai for Spring AI 2.x applications, or pendo-sdk-spring-ai-0x for Spring AI 1.1 or later. The Spring AI starter instruments every tool your application exposes, so you don't add the code in the next section. Set your Public App ID and Agent ID in application.properties as pendo.api-key and pendo.agent-id, or in the PENDO_API_KEY and PENDO_AGENT_ID environment variables.

If you aren't sure which version of the MCP Java SDK your server uses, run mvn dependency:tree -Dincludes=io.modelcontextprotocol.sdk.

Add the Java SDK to your server

Create one PendoMcpServer for your process, then pass your tool specifications through wrapAll() when you build the server. The SDK records only the tools you wrap, so wrap any tool you register later with 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();

Identify visitors and accounts in Java

If your server uses Streamable HTTP, add resolvers to the configuration so each tool call is tied to the visitor and account that made it. A resolver runs once per tool call and reads a value your transport stored, such as a header or an authenticated user.

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

A stdio server has no request to read from, so set fixed values with .visitorId() and .accountId() instead. If no visitor is set, the SDK records the visitor as anonymous and logs a warning once.

Set up a .NET MCP server

The .NET SDK works with servers built on version 2.3.0 or later of the ModelContextProtocol C# SDK. It's published to Pendo's NuGet feed, not nuget.org, so you add the feed as a package source before you add the package.

Install the .NET SDK

To add the feed and install the package, run:

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

To make the feed available on every machine that builds your project, add it to a nuget.config file next to your solution instead:

<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>

Add the .NET SDK to your server

Call WithPendoAgentAnalytics() on your MCP server builder. You can call it before or after you register your tools.

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();

The SDK reads any option you don't set from an environment variable, so you can call WithPendoAgentAnalytics() with no arguments:

Environment variable What it sets
PENDO_API_KEY Your Public App ID.
PENDO_AGENT_ID Your Agent ID.
PENDO_ENDPOINT The address the SDK sends data to. Defaults to https://app.pendo.io.
PENDO_VISITOR_ID A fixed Visitor ID for every tool call.
PENDO_ACCOUNT_ID A fixed Account ID for every tool call.
PENDO_DISABLED Set to true or 1 to turn the SDK off.

If the Public App ID or the Agent ID is missing, the SDK sends nothing and logs a warning that names the missing value. Your tools work the same either way.

Identify visitors and accounts in .NET

If your server uses Streamable HTTP, add resolvers so each tool call is tied to the visitor and account that made it. A resolver runs once per tool call and can read the authenticated caller.

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

A stdio server has no request to read from, so set fixed values with options.VisitorId and options.AccountId, or with the environment variables above. If no visitor is set, the SDK records the visitor as anonymous and logs a warning.

What the SDK changes on your server

After setup, the SDK records each tool call and sends it to Pendo. To capture why a tool was called, it adds a user_intent parameter to every tool your server lists and removes it before your tool runs, so your tool code doesn't change. It also adds a get_additional_tools tool, which records requests for capabilities your server doesn't have.

If your tests check the exact list of tools or parameters your server returns, update them to expect these additions.

The SDK groups tool calls into a conversation by the MCP session ID that Streamable HTTP clients send. A stdio server has no sessions, so the SDK can't group its tool calls by session.

Verify your setup

After setting up the SDK, run your server in your development or staging environment and call one of its tools from an MCP client. Then check your server log:

  • Python and TypeScript. The SDK logs a line each time it delivers data, for example Exported 8 event(s) to https://app.pendo.io/data/agenticsdk/<apiKey> [200, attempt 1]. The Python SDK logs through the logging module at the INFO level, which Python hides by default. To show these lines, add logging.basicConfig(level=logging.INFO, stream=sys.stderr) before you start your server.
  • Java and .NET. The SDK logs nothing when it delivers data and logs a warning when a delivery fails. Check for warnings that start with pendo: in Java or come from the Pendo.AgentAnalytics category in .NET.

Conversation data is processed in hourly batches. After your code is live in production, new data typically appears within 15 minutes after the start of the next batch. Go to Product > Agent Analytics and select your agent to confirm that your tool calls appear.

Troubleshooting

If data isn't appearing in Pendo, review these checks in order:

Check What to look for
Package not found when you build (Java, .NET) The Pendo repository or feed isn't configured in the build that resolves the dependency, or your network blocks pendo.jfrog.io.
No delivery line in your log (Python, TypeScript) In Python, turn on INFO logging as described in Verify your setup. Confirm that you set up the SDK before your server starts handling requests, and that you call your tools from an MCP client. Calling FastMCP's own list_tools() or call_tool() methods from Python bypasses the SDK.
A warning at startup says the SDK is disabled The Public App ID or the Agent ID wasn't found, or PENDO_DISABLED is set. Set both values in code or in the PENDO_API_KEY and PENDO_AGENT_ID environment variables, and remove PENDO_DISABLED.
Missing or incorrect Agent ID The Agent ID is required and must match an agent in the same app as your Public App ID. Pendo accepts events with an Agent ID it doesn't recognize, but doesn't show them.
Wrong Public App ID or endpoint A delivery warning with HTTP 401 means Pendo rejected the key. Verify that the value matches your Pendo Public App ID, that the endpoint matches your region, and that outbound traffic to it is allowed.
Your tool receives a user_intent parameter (Python, TypeScript) The SDK removes this parameter before your tool runs. If your tool still receives it, verify that your tools are registered on the server instance you passed to the SDK.
Tool calls rejected as invalid arguments (Java) Version 1.0 or later of the MCP Java SDK validates tool arguments, so a client that doesn't send user_intent is rejected. AI clients send it automatically. To accept clients that don't, call .validateToolInputs(false) on the server builder.
NoSuchMethodError or ClassNotFoundException at startup (Java) The artifact doesn't match your version of the MCP Java SDK. Use pendo-sdk-mcp for 1.0 or later and pendo-sdk-mcp-0x for 0.18.x.
The client reports a corrupted stream on a stdio server Something is writing to standard output, which stdio servers reserve for the MCP protocol. Send all logging, including the SDK's, to standard error or a file. In Python, don't call print(). In TypeScript, set console.log = console.error before you create your server.
Tool calls aren't grouped into one conversation Your MCP client isn't sending a session ID, or your server uses stdio.
Was this article helpful?
0 out of 0 found this helpful