Set up a custom agent in Agent Toolkit (beta)

Agent Toolkit lets you connect a custom agent to Pendo and equip it with Pendo capabilities. A custom agent is any AI agent other than Intercom Fin that you connect directly to Pendo — one you build in-house or a third-party agent you configure — in any framework that can call an MCP server over Streamable HTTP and receive HTTP webhooks.

If your agent runs on Intercom Fin, see Set up an agent in Agent Toolkit instead. For more information about Agent Toolkit, see Overview of Agent Toolkit.

Note: This feature is available in open beta.

Agent Toolkit is available only to admins. Non-admin users don't see Agent Toolkit in the main navigation and can't access its pages through a direct link.

How it works

You set up a custom agent in a single wizard with four steps:

• Agent details. Choose the agent type, name your agent, and select the apps it can access.
• Connect MCP. Set up the MCP connection, which powers guides, session context, and feedback submission.
• Set up proactive support. Give Pendo an endpoint to send events to, which powers workflow nudges and frustration signals.
• Review. Check your details and connections, then create the agent.

You must connect at least one of MCP or proactive support. This article covers making those connections. After the agent exists, you turn on and set up each capability from its tab on the agent. Each capability has its own article.

Setting up a custom agent takes two people:

• A Pendo admin runs the wizard.
• A developer writes the code that exchanges credentials for an access token, calls the MCP server, and receives webhook events.

Your developer can start before anyone opens the wizard. The wizard produces the credentials needed to run the integration, but not to write it. The sections before Step 1 cover what to build and in what order.

Note: When you add or update an agent, Pendo prevents you from linking a service account or webhook that's already linked to another Agent Toolkit agent. Unlink it from the existing agent before linking it to a different one.

Before you begin

To set up a custom agent in Agent Toolkit, you need:

• Subscription admin permissions to access Agent Toolkit.
• A developer or technical resource to implement the token exchange and, if you're using proactive support, the webhook receiver.
• A publicly reachable HTTPS endpoint, if you're using proactive support.

Plan your implementation

Your developer needs two things from Pendo: a client ID and a client secret. Both come from the wizard in Step 2, and your application can read them from configuration at runtime. Everything else is either fixed or chosen by you, so the code can be written and deployed before the wizard runs.

The following are all available before the wizard runs:

• The OAuth token URL and MCP server URL for your region. Both are listed in the sections below.
• The grant type, scope, and request encoding for the token exchange.
• The webhook payload shape and signature algorithm.
• Your own webhook endpoint URL and signing secret, which you choose.

That gives you this order:

1. Your developer builds and deploys the token exchange, and the webhook receiver if you're using proactive support.
2. A Pendo admin runs the wizard and copies the client ID and client secret from Step 2.
3. Your developer adds those two values to your application's configuration.
4. Your agent connects to Pendo.

Tip: Read the client ID and client secret from configuration or a secrets store rather than hardcoding them, and set your own webhook signing secret in Step 3 rather than having Pendo generate one. Then Step 3 above is a configuration change instead of a code change, and you avoid a second deployment.

If you're the Pendo admin and someone else is handling the code, skip to Step 1: Add an agent.

Build your token exchange

Your MCP client must exchange its credentials for an access token before it can call the Pendo MCP server. Pendo uses the OAuth 2.0 client credentials grant.

Token endpoint

Use the OAuth token URL that matches the region where your Pendo subscription is hosted. This is the same host name you use to sign in to Pendo. The wizard displays the correct URL for your subscription in Step 2.

Request parameters

Send a POST request with these parameters in the body, encoded as application/x-www-form-urlencoded:

Example request

curl -X POST "https://app.pendo.io/oauth/v1/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "scope=read:me"

Example response

{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Use and refresh the token

Pass the access token in the Authorization header on every request to the Pendo MCP server:

Authorization: Bearer {access_token}

Important: The scheme is case-sensitive. Use Bearer, not bearer, or the request is rejected as unauthenticated.

Tokens expire after the number of seconds indicated by expires_in, and no refresh token is issued. Your client must request a new token from the same endpoint before the current one expires. Request the replacement token ahead of expiry rather than waiting for a request to fail.

Build your webhook receiver

Skip this section if you're only using MCP capabilities.

Proactive support delivers real-time Pendo events to an HTTPS endpoint you host. Pendo sends a POST request with a JSON body and a Content-Type: application/json header. Your endpoint needs to accept that request, verify it came from Pendo, and return promptly.

Payload

Every event has the same top-level shape:

{
  "app": {
    "id": 1234567890,
    "name": "Example App",
    "platform": "web"
  },
  "accountId": "acme-corp",
  "subscription": {
    "id": 9876543210,
    "name": "Acme"
  },
  "userAgent": "Mozilla/5.0 ...",
  "event": "frustration",
  "properties": {},
  "timestamp": 1757337600,
  "visitorId": "visitor-1234",
  "atkEventType": "pendo-frustration-signal",
  "uniqueId": "a1b2c3d4"
}

Three fields matter for routing:

The properties field carries the event detail, and its contents depend on the capability. The timestamp field is a Unix timestamp in seconds. See each capability's article for the events it sends and what they contain.

Note: Ignore any event whose atkEventType your handler doesn't recognize rather than treating it as an error. The currently supported values are:

• pendo-frustration-signal
• pendo-net-request-signal
• pendo-workflow-nudge

Verify the signature

If you set a signing secret on the webhook in Step 3, Pendo adds an X-Pendo-Signature header to every request. It's the HMAC-SHA256 of the raw request body, keyed with your secret, hex-encoded.

Verify it against the raw body, before any JSON parsing, and compare in constant time:

const crypto = require('crypto');

function isValidSignature (rawBody, signatureHeader, secret) {
    const expected = crypto
        .createHmac('sha256', secret)
        .update(rawBody)
        .digest('hex');

    const received = Buffer.from(signatureHeader || '', 'utf8');
    const computed = Buffer.from(expected, 'utf8');

    return received.length === computed.length
        && crypto.timingSafeEqual(received, computed);
}

Important: If you don't set a signing secret, Pendo sends no X-Pendo-Signature header and your endpoint can't verify that a request came from Pendo. Set a secret unless you have another way to authenticate the caller.

Step 1. Add an agent

1. Go to Agent Toolkit in the main navigation.
2. Select Add agent to open the setup wizard.
3. Under Agent type, select Custom agent.
4. Enter a Name for the agent and optionally a Description.
5. Under Accessible apps, select at least one web app the agent can access. This field is required, and it determines which data your agent can reach. Mobile and extension apps aren't supported.
6. Select Continue.

Note: The agent type is saved with the agent and can't be changed after the agent is created.

Step 2. Connect MCP

The MCP connection lets your agent query live Pendo data, which powers guides, session context, and feedback submission. If you don't need these capabilities, select Skip and set up proactive support instead.

Note: Turning on the MCP server enables MCP for your subscription. This means users can read and write Pendo data outside of the Pendo application. For more information, see Overview of the Pendo MCP server.

1. In the wizard, turn on MCP server. Pendo creates a service account for this agent.
2. Under Create connection, copy the credentials the wizard displays. Your developer needs all five:
   • MCP server URL
   • OAuth token URL
   • Client ID
   • Client secret
   • Scope
3. Give the client ID and client secret to your developer, or add them to the configuration your application already reads. Your application exchanges them for an access token on a refresh loop, as described in Build your token exchange.
4. Select I configured my agent to request and renew OAuth access tokens and I configured my agent to use the access token to authenticate MCP requests. You can't continue until both are selected.
5. Select Continue.

Important: Save the client secret somewhere secure now. Pendo can't show it again after you leave the wizard. If you lose it, you must rotate the secret to generate a new one, which immediately invalidates the old one.

A service account can be linked to only one Agent Toolkit agent. If you already have a service account you want to reuse, unlink it from its current agent first. See Authenticate to the Pendo MCP server with a service account.

Step 3. Set up proactive support

Proactive support pushes real-time Pendo events to your agent, which powers workflow nudges and frustration signals. If you don't need these capabilities and you've connected MCP, select Skip.

Note: If you skipped MCP, a proactive support connection is required to proceed and create an agent.

1. Enter the URL of the endpoint Pendo sends events to. It must be a publicly reachable HTTPS URL of 1024 characters or fewer.
2. Set a Secret. You can enter your own, or select Generate to have Pendo create a random one. Pendo uses this to sign every request so your endpoint can verify it. If you generate one here, save it somewhere secure and add it to your endpoint's configuration.
3. Select Create connection.
4. Select Continue.

Note: The connection starts inactive and won't send events until you set up and turn on its capabilities after agent setup is complete. Your endpoint doesn't have to be live to finish the wizard, but it must be live before you turn on workflow nudges or frustration signals.

Step 4. Review

On the Review step, confirm your agent details and connection setup. At least one of MCP or proactive support must be connected.

1. Check the summary: agent type, name, apps, MCP status, and proactive support status.
2. Select Add agent.

Pendo creates the agent and opens its overview page, where you can start enabling capabilities.

Connect and verify

With the agent created and your credentials in place, connect your MCP client to Pendo and confirm it can reach the tools.

MCP endpoint

Point your MCP client at the MCP server URL for your region. This is the same URL the wizard displayed in Step 2.

This endpoint uses the Streamable HTTP transport. Send JSON-RPC requests to this URL with the Authorization: Bearer {access_token} header from Build your token exchange.

Initialize the session

curl -X POST "https://app.pendo.io/mcp/visitor/shttp" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {access_token}" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2025-06-18", "capabilities": {}, "clientInfo": {"name": "your-agent-name", "version": "1.0"}}}'

A successful response returns the server's capabilities.

The server accepts the protocol versions 2025-11-25, 2025-06-18, 2025-03-26, and 2024-11-05. It replies with the version your client requested, or with the most recent version it supports if your client requests one it doesn't recognize.

The response also includes an Mcp-Session-Id header. Echo it in subsequent requests if your client tracks sessions, or omit the header entirely. Don't invent a value: a malformed session ID is rejected.

Note: After receiving the initialize response, send a notifications/initialized notification to complete the handshake before calling any tools.

List the available tools

Call tools/list after the handshake completes to confirm the connection works and see which tools your agent can use:

curl -X POST "https://app.pendo.io/mcp/visitor/shttp" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {access_token}" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}'

The tools your agent sees depend on your subscription's entitlements and settings, and on which capabilities you've enabled. If a tool you expect is missing, check the prerequisites in its capability article.

You don't need to identify your subscription in any call. Pendo resolves it from the credentials your client authenticated with.

Next steps

Your agent is connected. Turn on and set up capabilities from the agent's tabs in Agent Toolkit.

The MCP connection powers:

• Guides. Your agent surfaces a relevant Pendo guide in response to a visitor's question. For more information, see Deliver guides through your AI agent.
• Session context. Your agent draws on a visitor's recent activity in your product when it responds.
• Feedback submission. Your agent sends visitor feedback to Pendo from within the conversation.

The proactive support connection powers:

• Workflow nudges. Your agent re-engages a visitor who drops off partway through a workflow you define.
• Frustration signals. Your agent responds when Pendo detects friction, such as a rage click, error click, or U-turn.

Turn on the proactive support connection when your endpoint is live. Until you do, Pendo won't deliver events.