ThousandEyes MCP Server

The Model Context Protocol (MCP) standardizes how applications can provide context to large language models (LLMs), allowing AI assistants to access and query external data and tools/APIs, and incorporate the results of those queries in their responses.

The ThousandEyes MCP server allows you to connect an AI assistant directly to the ThousandEyes platform. The assistant can then use natural language to access and analyze ThousandEyes network monitoring data through a standardized interface.

Prerequisites

To use the ThousandEyes MCP server, your organization must not be opted out of ThousandEyes AI features. In addition, you will need:

• The API Access ThousandEyes user permission. Any user with this permission will be able to use the MCP server.

• A ThousandEyes API token.

• An MCP-compatible client.

For instructions on generating a new API token, see User API Tokens.

For more information on user permissions, see Role-Based Access Control.

Availability and Rate Limits

Access to the ThousandEyes MCP Server is currently available at no additional cost to all ThousandEyes customers.

ThousandEyes reserves the right to modify service packaging, feature availability, and pricing structures in future releases at our discretion.

ThousandEyes MCP server usage counts against your API rate limit, but the specific limit depends on your authentication method:

• OAuth Bearer Token: Usage counts against your organization-wide rate limit (typically 240 requests per minute). This usage is shared with other integrations using standard API tokens. For more information, see Rate Limits.

• OAuth 2.0 Access Token: Each OAuth2 client has its own separate rate limit of 240 requests per minute. This usage does not affect your organization-wide rate limit.

If you need to increase your rate limit, contact ThousandEyes Support.

Connect to the MCP Server

To integrate the ThousandEyes MCP server with your AI assistant, you will need to either create an MCP client, or use a framework that supports MCP, and configure it to authenticate to the MCP server.

The sections below outline example configurations for common MCP-compatible clients. Refer to the relevant client documentation for more detailed instructions.

The configurations shown below are examples. You will need to adapt the configuration for your own needs. For example, Windows users will need to replace the command line to specify the location of npx. This may look something like:

"command": "C:\\Progra~1\\nodejs\\npx.cmd"

In addition, the <THOUSANDEYES_API_TOKEN> variable should be replaced with your API token.

OpenAI Codex

To connect the ThousandEyes MCP server with OpenAI Codex:

1. Set the API token as an environment variable called TE_TOKEN so that it can be accessed by the environment that launches Codex.

2. In Codex, navigate to Settings > MCP Servers.

3. Click Add Server +.

   

   Codex by ChatGPT Add MCP Server Page
4. Set the Name to something like ThousandEyes MCP Server or ThousandEyes.

5. Set the Bearer token env var to TE_TOKEN.

6. Set the Bearer header to your ThousandEyes API token.

7. Click Save.

8. Restart Codex.

Claude

You can connect the ThousandEyes MCP server to Claude using a custom connector:

If you use the free version of Claude, you can only add the ThousandEyes MCP server as a custom connector with the Claude Desktop app. Custom connectors can only be added to Claude via the web browser by paid users.

1. In Claude, go to Settings > Connectors > Add custom connector.

   

   Claude Custom Connector Setup
2. Set the Name to ThousandEyes MCP Server.

3. Set the Remote MCP server URL to https://api.thousandeyes.com/mcp.

4. Click Add.

5. When a browser window opens, sign in with your ThousandEyes credentials and agree to share your DCR token with Claude.

Once the connector is added, click Configure for the ThousandEyes MCP Server and turn on auto-allow for tools. This will allow the tools to run automatically, rather than requiring user approval each time.

There are two groups of tools: Read-only tools and Write/delete tools. Configure permissions for each group as needed.

Cursor IDE

The Cursor IDE's MCP client allows for the direct specification of custom HTTP headers, with the Authorization header sent with every request to the MCP server. You can also install the Cisco ThousandEyes Cursor plugin from the marketplace.

Cursor Plugin

You can find the Cisco ThousandEyes Cursor plugin here: Cursor Marketplace.

OAuth Bearer Token

{
  "mcpServers": {
    "ThousandEyes": {
      "url": "https://api.thousandeyes.com/mcp",
      "headers": {
        "Authorization": "Bearer <THOUSANDEYES_API_TOKEN>"
      }
    }
  }
}

OAuth2 flow

If the OAuth2 authentication flow is used, a browser is required to enable access and to share the token with the client.

{
  "mcpServers": {
    "ThousandEyes": {
      "url": "https://api.thousandeyes.com/mcp"
    }
  }
}

VS Code

VS Code's input variables allow you to create a secure prompt within the IDE for the user to enter their API token, rather than hardcoding the token into a configuration file.

The ${input:te-key} variable is then dynamically replaced with the entered key at runtime, preventing the token from being accidentally saved to source control.

Additional Prerequisites:

• You will need to install Node.js to use VS Code. For instructions, see the Node.js documentation.

• Copilot features must be enabled in VS Code.

OAuth Bearer Token

{
  "inputs": [
    {
      "type": "promptString",
      "id": "te-key",
      "description": "ThousandEyes API Key",
      "password": true
    }
  ],
  "servers": {
    "ThousandEyes": {
      "url": "https://api.thousandeyes.com/mcp",
      "headers": {
        "Authorization": "Bearer ${input:te-key}"
      }
    }
  }
}

AWS Kiro

Use the configuration examples below as a basis for creating a ~/.kiro/settings/mcp.json file.

Additional Prerequisites:

• You will need to install Node.js to use AWS Kiro. For instructions, see the Node.js documentation.

OAuth Bearer Token

{
  "mcpServers": {
    "ThousandEyes": {
      "command": "npx",
      "args": [
        "mcp-remote@latest",
        "https://api.thousandeyes.com/mcp",
        "--transport",
        "http-only",
        "--header",
        "AUTH_TOKEN": Bearer ${AUTH_TOKEN}
      ],
      "env": {
        "AUTH_TOKEN": "<THOUSANDEYES_API_TOKEN>"
      }
    }
  }
}

OAuth2 Flow

If the OAuth2 authentication flow is used, a browser is required to enable access and to share the token with the client.

{
  "mcpServers": {
    "ThousandEyes": {
      "command": "npx",
      "args": [
        "mcp-remote@latest",
        "https://api.thousandeyes.com/mcp",
        "--transport",
        "http-only"
      ]
    }
  }
}

MCP Server Functionality and Sample Prompts

You can currently call the following tools with the MCP server installed:

We recommend being selective with the tools you enable. Enabling too many tools at once can lead to degraded MCP server performance, including delayed responses and timeouts.

Core Monitoring

Tool	Description	Sample Prompts
List Tests	View all configured tests (web apps, services, networks being monitored).	What tests am I running? ​What apps am I monitoring?
Get Test Details	Retrieve detailed information about a specific test.	Can you provide me details of the test name test?​
List Events	Find network and application problems within a time range.	Do I have any active events? Were there any active events at 3pm today?
Get Event Details	Deep dive into specific events with impacted targets, locations, and agents.	Can you provide detail for event name or event number from the list?
List Alerts	View triggered or cleared alerts.	Do I have any active alerts? Do I have any alerts for time?
Get Alert Details	Get comprehensive information about specific alerts.	​Can you provide me more details of the critical alert?
Search Outages	Find network and application outages with various filters.	What outages have occurred in the last 24 hours? Can you provide me more details about app/network outage?
Instant Tests	Run, rerun, and retrieve real-time results for on-demand tests during active troubleshooting sessions.	Run an HTTP test to https://example.org from our Seattle and San Francisco agents. Show me the results for instant test 12345.

Unit Consumption for Instant Tests:

When asking the assistant to run an "Instant Test," the platform executes a live test that consumes units. The pricing is identical to scheduled tests, but is billed for a single round. For details, see Configuration-Based Consumption Model.

Test Management

Tool	Description	Sample Prompts
Create Synthetic Test	Create new scheduled synthetic tests for network and application monitoring. All synthetic test types are supported.	Create an HTTP synthetic test for https://example.org from our Seattle and San Francisco agents. Create a DNS server synthetic test for www.example.com using 8.8.8.8 from my US agents.
Update Synthetic Test	Update an existing scheduled synthetic test, including its target, interval, agents, or configuration.	Update synthetic test 12345 to run every 5 minutes. Change synthetic test 12345 to target https://api.example.org/health.
Delete Synthetic Test	Delete a scheduled synthetic test that is no longer needed.	Delete synthetic test 12345. Remove the old DNS synthetic test for example.com.

Alert Rule Management

Tool	Description	Sample Prompts
List Alert Rules	List alert rules for ThousandEyes synthetics, Endpoint Agents, Connected Devices, Cloud Insights, and Traffic Insights.	List alert rules in my current account group. Show alert rules for account group account group ID.
Get Alert Rule	Retrieve one alert rule, including its expression, severity, notification settings, and violation criteria.	Show details for alert rule alert rule ID, including its expression and severity.
Create Alert Rule	Create an alert rule with an expression, alert type, severity, violation window, and optional notification settings.	Create a minor HTTP server alert rule named API Availability when availability drops below 100%. Create an end-to-end network alert rule for average latency above 1000 ms.
Update Alert Rule	Update an existing alert rule. Include the rule ID and the rule payload fields you want to preserve or change.	Update alert rule alert rule ID to use severity minor. Change alert rule alert rule ID to alert after 3 of 5 violating rounds.
Delete Alert Rule	Delete an alert rule by ID.	Delete only alert rule alert rule ID after verifying it is no longer assigned to active tests.

​​​​

Dashboard Management

Tool	Description	Sample Prompts
List Dashboards	List dashboard summaries in the current account group.	List dashboards in my current account group. Show dashboard summaries for account group account group ID.
Get Dashboard	Retrieve a dashboard definition, including its configured widgets.	Open dashboard dashboard ID and show its widgets. Get the dashboard definition for Health Overview.
Get Dashboard Widget Data	Retrieve the raw data rendered by a specific dashboard widget. Supports time windows and pagination.	Fetch data for widget widget ID on dashboard dashboard ID for the last hour. Show the next page of widget data using cursor cursor value.
Create Dashboard	Create a new dashboard, optionally with widgets and privacy settings.	Create a private dashboard named API Operations Overview. Create an empty dashboard for account group account group ID.
Update Dashboard	Update an existing dashboard, including its title, description, privacy setting, global filter, or widgets.	Rename dashboard dashboard ID to API Operations Overview. Clear all widgets from dashboard dashboard ID.
Delete Dashboard	Delete a dashboard by ID.	Delete only dashboard dashboard ID after I confirm it is no longer needed.

​

Endpoint Monitoring​

Tool	Description	Sample Prompts
List Endpoint Agents and Tests	List Endpoint Agents and/or tests with filtering.	Show me all my Endpoint Agents. What Endpoint Agents do I have deployed?
List Endpoint Agent Dynamic Tests	List configured Endpoint Agent dynamic tests, including test name, monitored application, interval, protocol, and enabled state.	List my Endpoint Agent dynamic tests and include each test's application and interval. Which dynamic tests are configured for Endpoint Agents in this account group?
Get Endpoint Agent Metrics	Time series data from Endpoint Agents (network, web, wireless, cellular metrics).	Get all Endpoint Agent data for the last hour. Get Endpoint Agent metrics for network performance.
Get Endpoint Scheduled Test Results	Retrieve network results for a scheduled Endpoint Agent test, including latency, packet loss, jitter, and bandwidth. Supports time windows and pagination.	Get network results for Endpoint scheduled test test ID for the last 24 hours. Show latency and packet loss for Endpoint scheduled test test ID from yesterday.
Get Connected Device	Get full details for one Connected Device by agent_id: connection status, uptime, version, location, network quality, and health. Defaults to last 24 hours.	Get full Connected Device info for agent ID abc123xyz.

Network Path Analysis​

Tool	Description	Sample Prompts
Get Path Visualization	See network paths and hop-by-hop routing information.	What is the hop-by-hop network path for my test from agent at time?​
Get Full Path Visualization	Comprehensive path data for all agents and rounds	What is the network path for test? Which locations are network exchanges? Which have mpls hop label = label?
Get BGP Test Results	BGP reachability and routing information.	What are the BGP test results for test name at time and date?
Get BGP Route Details	Detailed AS path and routing information for specific prefixes.	Can you provide route details from route monitor at time and date?

​

Agent Management

Tool	Description	Sample Prompts
Get Cloud and Enterprise Agents	List Cloud and Enterprise Agents with filters such as agent type, location, country, and enabled status.	Show me all Enterprise Agents in the US. List my enabled Cloud Agents in London.

​​

Account Management ​

By default, queries are scoped to your default account group. To expand the scope to multiple or all account groups, you can specify which account groups you want data retrieved from in your prompt to the MCP server.

​​​

Tool	Description	Sample Prompts
Get Account Groups	List available account groups.	What is my default account group? What account groups have app tests in them?

Tag Management

Tool	Description	Sample Prompts
List Tags	List key-value tags in an account group, including static assignments where available.	List tags in my current account group with assignments. Show tags for account group account group ID.
Get Tag	Retrieve one tag by ID, including tag metadata and static assignments.	Show tag tag ID and its assignments.
Create Tag	Create a static or dynamic key-value tag for one supported object type. Include the access type for writable tags. Dynamic tags are supported only for Endpoint Agents.	Create a static dashboard tag team:netops with access type all. Create a dynamic Endpoint Agent tag network:corp-wifi with access type all for agents on SSID Corp-*.
Update Tag	Update tag metadata such as key, value, description, color, assignment type, or Endpoint Agent dynamic filters.	Update tag tag ID description to Used by Network Operations. Clear the icon from tag tag ID.
Assign Tags	Assign a static tag to supported objects such as tests, dashboards, agents, Endpoint Agent scheduled tests, and Connected Device tests.	Assign tag tag ID to dashboard dashboard ID. Assign tag tag ID to test test ID.
Unassign Tags	Remove static tag assignments from supported objects.	Unassign tag tag ID from dashboard dashboard ID.
Delete Tag	Delete a tag by ID.	Delete only tag tag ID after verifying it is no longer assigned.

Template Management

Tool	Description	Sample Prompts
Search Templates	List the available templates for your account group and optionally filter them by name.	What templates are available in my account group? Find templates related to endpoint monitoring.
Deploy Template	Deploy a template to create tests, dashboards, alert rules, or other assets using the required input values.	Deploy the template template name for example.com using my Seattle agents. Use template template name to create monitoring for api.example.com.

AI-Powered Skills​

Tool	Description	Sample Prompts
Views Explanations	Explain specific test results and visualizations.	Explain the network path for test at time/date.

Advanced Analysis

Tool	Description	Sample Prompts
Get Anomalies	Detect metric anomalies in test data over time.	Can you find anomalies during time period for test test name?​
Get Metrics	Retrieve aggregated metrics for custom dashboards and reports.	Can you retrieve the metrics for the test name from time/date?​
Get Service Map	Retrieve a distributed tracing service map for supported HTTP server tests when distributed tracing is enabled.	Show me the service map for HTTP test test name from the last hour. For HTTP test test name, show the traced services involved in the request flow.

Troubleshooting

If you are using an MCP server client that uses npx, and encounter the command not found error, you may not have Node.js installed. For instructions, see the Node.js documentation.

You can use the following commands to verify Node.js is installed correctly in a terminal:

# bash% node --version
v22.18.0
# npx --version
10.9.3