Deliver guides through your AI agent (beta)

Agent Toolkit lets your AI agent surface relevant Pendo guides directly in chat conversations. When a visitor asks how to complete a task, your agent queries Pendo through the Model Context Protocol (MCP) and offers a walkthrough the visitor can launch in your app.

This article covers agents you build and host yourself. If your agent runs on Intercom Fin, see Serve Pendo guides using Intercom Fin instead. The setup is the same up to the point where you connect the tool, and that article covers the Intercom side.

Note: This feature is available in closed beta. To request access, fill out the MCP Support Agents interest form. Your Pendo account representative will follow up to turn it on for your subscription.

Use cases

Use this integration to:

• Deliver interactive, step-by-step walkthroughs in response to support questions, instead of static text answers.
• Reduce inbound support volume by giving visitors immediate, contextual help.
• Respect your existing Pendo segment rules and guide targeting when delivering guides, so a visitor is only ever offered a guide they're eligible to see.
• Reuse the guide library you already maintain, from any agent framework that can call an MCP server over Streamable HTTP.

How it works

Your agent reaches Pendo through the same MCP connection you set up in Agent Toolkit. The end-to-end flow works like this:

1. A visitor asks your agent a question in your app's chat.
2. Your agent recognizes the question as a request for help with a task.
3. Your agent calls the getInAppGuidance tool on the Pendo MCP server, passing the visitor's question and, optionally, their Pendo Visitor ID.
4. Pendo narrows your guide library to the guides that visitor is eligible to see, based on your existing segment rules and guide targeting, and returns the single most relevant match.
5. Your agent surfaces the guide as a link the visitor can select to launch the walkthrough in your app.

Before you begin

To complete this setup, you need:

• Beta access to this feature. To request access, fill out the MCP Support Agents interest form. Your Pendo account representative will turn it on for your subscription.
• Agent Toolkit turned on for your subscription. A subscription admin turns this on in Settings > Subscription settings > AI access > Agent Toolkit. Turning it on also turns on the settings Agent Toolkit depends on, including service accounts, webhooks, and Semantic search. Agent Toolkit requires a paid Pendo subscription.
• Semantic search turned on. This is turned on with Agent Toolkit. If it's off, your subscription may have opted out of Google AI features, and the getInAppGuidance tool is unavailable.
• Subscription admin permissions. 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.
• A developer or technical resource to configure the token refresh and MCP connection.

Step 1. Create an agent in Agent Toolkit

Agent Toolkit creates the service account your agent authenticates with and gives you the connection values you need in Steps 3 and 4. Everything here happens in Pendo.

1. Go to Agent Toolkit in the main navigation, then select Add agent.
2. Under Agent type, select Custom Agent.
3. Enter a Name for the agent, and a Description if you want one.
4. Under Accessible apps, select at least one app. This is required, and it determines which guides your agent can return: the agent can only see guides belonging to the apps you select here.
5. Select Continue.
6. On the Connect MCP step, turn on MCP server. Pendo creates a service account for this agent.
7. Copy the values the wizard displays. You need all five:
   • OAuth token URL
   • Client ID
   • Client secret
   • Scope
   • MCP server URL

8. Confirm that you've saved the client secret. You can't continue until you do.

   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.

9. Select Continue. On the Set up webhooks step, select Skip. Webhooks power task nudges and frustration signals, not guides.
10. On the Review step, check the agent details and confirm that MCP is connected, then select Add agent.

Pendo creates the agent and opens its overview page. For more detail on the wizard, including the capabilities you can add later, see Set up an agent in Agent Toolkit.

Note: 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. You can also create one by hand in Settings > Integrations > Service accounts, though Agent Toolkit is the recommended path. See Authenticate to the Pendo MCP server with a service account.

Step 2. Make your guides available to your agent

Your agent can only return a guide that's eligible for Agent Toolkit and has an activation URL. You set this up on the agent's Guides tab.

Go to Agent Toolkit, select your agent, then open the Guides tab. Each row shows the guide's Eligibility, its Activation URL, Target segment, and Target Page.

Set an activation URL

The activation URL is the page Pendo sends the visitor to in order to launch the guide. A guide without one stays Inactive and is never returned.

1. Find the guide and open its quick edit panel.
2. In Activation URL, enter the URL where the guide's first step appears. It must match the page rule for that first step.
3. To have Pendo propose one based on where the guide has recently launched, select Suggest an activation URL. If the guide hasn't launched often enough, no suggestion is offered.
4. Save your change. Pendo validates the URL and updates the guide's status.

Use dynamic attributes in an activation URL

If the URL differs from visitor to visitor (an account ID in the path, for example), insert a dynamic attribute instead of a literal value. Type @ in the Activation URL field and either pick an existing attribute or create one. Pendo stores it as {{attributeName}}.

Your client supplies the values at call time through the attributes parameter, described in Step 5. A guide whose activation URL contains a placeholder your client doesn't supply a value for is left out of the results, so make sure your client can fill every attribute you use.

Check the guide's eligibility

The Eligibility column tells you whether the guide can be returned:

Unsupported guide types

Some guide types can't be used with Agent Toolkit and always show an Unsupported eligibility:

• Guides set to non-public visibility.
• Resource Center guides.
• Guides associated with more than one application.
• Embedded guides.
• Guides with no steps.

Step 3. Authenticate your MCP client

Your MCP client must exchange the credentials from Step 1 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 the wizard gave you in Step 1. It matches the region where your Pendo subscription is hosted, which is the same host name you use to sign in to Pendo.

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.

Step 4. Connect to the MCP endpoint

Point your MCP client at the MCP server URL the wizard gave you in Step 1. It matches the region where your Pendo subscription is hosted, which is the same host name you use to sign in to Pendo.

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

Example: Initialize the MCP 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. To retrieve the list of available tools, call tools/list after the handshake completes.

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.

Step 5. Call the getInAppGuidance tool

getInAppGuidance is the tool your agent calls to find a guide. It takes the visitor's question, narrows your guide library to what that visitor is eligible to see, and returns the single best match.

Parameters

Important: hostname and attributes must be set by your client code, not by the agent. Don't expose them to the model or describe them in your system prompt.

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

Visitor ID and guide eligibility

What you pass as visitorId decides which guides are eligible:

• Omitted. Only guides with no segment targeting are returned. Use this when your agent can't reliably identify the visitor.
• Provided. Pendo evaluates the visitor against your segment rules and guide targeting, and returns guides that visitor is eligible to see, including segment-targeted ones.

Example request

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/call", "params": {"name": "getInAppGuidance", "arguments": {"query": "How do I set up single sign-on?", "visitorId": "visitor-1234"}}}'

Example response

The tool returns one text content block. Its text is a JSON object describing a single guide:

{
  "Id": "kD3nR7xQ_a1B2c",
  "Type": "Guide",
  "Name": "Set up single sign-on",
  "Description": "Walks an admin through configuring SAML SSO.",
  "activationUrl": "https://app.example.com/settings/security?pendo=RMz6L_ZaNHIlvzSZ4HHwO4wbGLk&step=oZNPUs6q_zOiwyJSzOeWJ7x6Poo&pendosource=atk",
  "GuideContent": "Go to Settings, then select Security..."
}

When no guide matches, the tool returns this text instead of a JSON object:

No relevant in-app guides were found for the search query.

Step 6. Update your agent's instructions

The MCP server advertises the tool's name, description, and parameters through tools/list, so you don't need to write a tool description yourself. Add the following to your agent's system prompt:

• When to call the tool. Treat "How do I…", "Help me with…", and similar requests for help completing a task as a signal to call getInAppGuidance.
• What to pass as query. The visitor's question, either verbatim or rephrased to include context from earlier in the conversation.
• How to present the result. Render activationUrl as a clickable link labeled with the guide's name, using whichever format your chat interface supports. For example, [Guide name](activationUrl) in Markdown, or <a href="activationUrl">Guide name</a> in HTML.
• What to do when no guide matches. Answer the question normally. Don't show the "No relevant in-app guides were found" text to the visitor.