Welcome to Pathfinder MCP gateway

🚧

Important information

• We strongly recommend using BT PF MCP only with enterprise AI subscriptions, not personal AI subscriptions which do not afford the data protections of enterprise plans. If you’re not sure what’s ok in your organization, check with your information security team, or technology leaders on your organization’s policy.
• Using the Pathfinder MCP is optional and is available on an opt-in basis. See Configure Pathfinder MCP to learn more.
  You can try Pathfinder MCP and opt out at any time.

What is the Pathfinder MCP Gateway?

The Pathfinder MCP gateway is a single endpoint that lets AI agents securely query data from across your BeyondTrust products. Instead of building integrations against individual product APIs, your agent connects to one MCP-compatible endpoint and discovers available tools automatically – covering Identity Security Insights, Entitle, Password Safe, EPM, Privileged Remote Access, Remote Support, and more.

The gateway uses the Model Context Protocol (MCP), an open standard based on JSON-RPC 2.0. Any AI agent or client that supports MCP can connect.

ℹ️

• The intentional design of this system mitigates the potential impact of prompt injection
• Exposing Insights data is a core part of our functionality and is therefore not a vulnerability
• Usage of our LLM agent for other use cases (e.g general LLM questions) is acceptable. While not encouraged, we see no reason why customers can't use our LLM given that they are paying for it

Prerequisites

Before connecting an agent to the MCP gateway:

• MCP enabled on your site: An administrator must set the Platform Model Context Protocol (MCP) to "Read Only" in the site settings. See Administration documentation.
• MCP access token: Generate a token from your Pathfinder profile. See Generate an MCP Access Token.
• MCP-compatible AI agent or client: Any tool that supports the Model Context Protocol, such as:
  • VS Code with MCP extension
  • Claude Code / Claude Desktop
  • Cursor
  • Custom internal agents or chatbots
  • Partner integrations (e.g., Microsoft Security Copilot)
  • JSON-RPC 2.0 support: The gateway communicates using the MCP specification over HTTP POST.

Connect your agent

All agents connect through a single endpoint. Configure your MCP client with:

• Server URL: https://mcp.beyondtrust.io/mcp
• Authorization header: Authorization: Bearer

VS Code configuration example

Add the following to your VS Code MCP settings:

{  
  "inputs": [  
    {  
      "id": "pathfinder-token",  
      "type": "promptString",  
      "description": "MCP access token for Pathfinder",  
      "password": true  
    }  
  ],  
  "servers": {  
    "pathfinder": {  
      "type": "http",  
      "url": "<https://mcp.beyondtrust.io/mcp">,  
      "headers": {  
        "Authorization": "Bearer ${input:pathfinder-token}"  
      }  
    }  
  }  
}

Claude Code configuration example

claude mcp add pathfinder <https://mcp.beyondtrust.io/mcp>  
  --transport http  
  --header "Authorization: Bearer <your-mcp-token>"

What the gateway does

Once connected, your agent can:

• Discover tools: The gateway exposes tools from every BeyondTrust product configured on your site. Your agent calls tools/list to enumerate all available tools, their descriptions, and input schemas.
• Query data: Call any discovered tool to retrieve data from the corresponding BeyondTrust product. All operations are read-only (list, get, show, and index).
• Handle structured responses: Each tool returns structured JSON responses containing the queried data, which your agent can interpret, summarize, or use as context for follow-up queries.

The gateway enforces your Pathfinder identity on every call. Your agent can only access what the token owner is permitted to access. No additional privileges are granted through MCP.

Available products

The gateway aggregates tools from the following BeyondTrust products. Tools are namespaced by product category.

ℹ️

Note:

The tools available to your agent depend on which BeyondTrust products are licensed and configured on your site. If a product is not active, its tools will not appear in the gateway.

Product version requirements

The following table lists the minimum product versions required for MCP gateway compatibility.

ℹ️

Some products require additional in-app configuration to expose tools through the MCP gateway. Refer to the product-specific documentation at docs.beyondtrust.com for setup steps.

Permissions

Gateway access

The MCP gateway validates your token and enforces permissions on every call. The gateway does not bypass BeyondTrust product security. For each tool your agent calls, the user behind the token must already hold the correct roles in that product within Pathfinder.

Product-level roles

If the token owner does not have the required role for a specific product action, the gateway returns an error in the response body. For example, if the user does not have access to Password Safe, tools in the password-safe___ namespace will return an authorization error.

Example scenario

Use case: Your security team wants an AI assistant in VS Code to help investigate identity risks across your BeyondTrust environment.

Step 1: Enable MCP

A Pathfinder administrator enables MCP on the site by setting the Platform Model Context Protocol (MCP) dropdown to "Read Only" in the site settings. See Administration documentation.

Step 2: Generate a token

The security analyst navigates to their profile and generates an MCP access token with a 90-day expiration. See Generate an MCP Access Token.

Step 3: Configure the agent

The analyst adds the Pathfinder MCP server to their VS Code MCP settings using the endpoint and token.

Step 4: Query your environment

The agent connects, discovers available tools, and the analyst can now ask questions like:

• "Pull the top 5 security recommendations from Insights, ordered by severity."
• "List all managed systems in Password Safe."
• "Show me the Entitle permissions for this integration."
• "What EPM policies are configured?"
• "Show PRA session activity for the past 90 days."

The agent calls the appropriate MCP tools and returns structured answers grounded in your live environment data.

Step 5: Pathfinder enforces access controls

Every tool call is processed under the analyst's Pathfinder identity. The gateway enforces the same product-level roles and permissions that apply throughout Pathfinder. The agent sees only what the analyst is permitted to see.

Error handling

The MCP gateway returns HTTP 200 for all requests it successfully processes – including cases where a backend product returns an error. Errors from downstream products appear in the JSON response body, not in the HTTP status code.

Common error patterns:

When building agents or reviewing agent output, check the response body for error details rather than relying on the HTTP status code alone.

Data access

The MCP gateway queries data from the BeyondTrust products configured on your site. It does not connect to external systems directly, it works with the data your licensed products manage within Pathfinder.

To expand what your agent can query, ensure the relevant BeyondTrust products are licensed, configured, and that the token owner has the appropriate roles. See Product-Specific configuration for details.