# 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](https://docs.thousandeyes.com/product-documentation/user-management/authorization/rb-access-control#user-api-tokens). For more information on user permissions, see [Role-Based Access Control](https://docs.thousandeyes.com/product-documentation/user-management/authorization/rb-access-control). ## Availability and Rate Limits Access to the ThousandEyes MCP Server is currently available at no additional cost to all ThousandEyes customers. {% hint style="info" %} ThousandEyes reserves the right to modify service packaging, feature availability, and pricing structures in future releases at our discretion. {% endhint %} 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](https://developer.cisco.com/docs/thousandeyes/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. {% hint style="info" %} If you need to increase your rate limit, contact ThousandEyes Support. {% endhint %} ## 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. {% hint style="info" %} 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 `` variable should be replaced with your API token. {% endhint %} ### 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](/files/lWcbALKsalJonPymt78e) 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: {% hint style="warning" %} 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. {% endhint %} 1. In Claude, go to **Settings** > **Connectors** > **Add custom connector**. ![Claude Custom Connector Setup](/files/bQ3PAoKwbEomKaYvLpsg) 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. {% hint style="info" %} There are two groups of tools: **Read-only** tools and **Write/delete** tools. Configure permissions for each group as needed. {% endhint %} ### 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](https://cursor.com/marketplace/cisco-thousand-eyes). **OAuth Bearer Token** ``` { "mcpServers": { "ThousandEyes": { "url": "https://api.thousandeyes.com/mcp", "headers": { "Authorization": "Bearer " } } } } ``` **OAuth2 flow** {% hint style="info" %} If the OAuth2 authentication flow is used, a browser is required to enable access and to share the token with the client. {% endhint %} ``` { "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](https://nodejs.org/en/download). * 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](https://nodejs.org/en/download). **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": "" } } } } ``` **OAuth2 Flow** {% hint style="info" %} If the OAuth2 authentication flow is used, a browser is required to enable access and to share the token with the client. {% endhint %} ``` { "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: {% hint style="warning" %} 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. {% endhint %} **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 from our Seattle and San Francisco agents.
  • Show me the results for instant test 12345.
| {% hint style="warning" %} **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](https://docs.thousandeyes.com/product-documentation/user-management/usage-and-billing/our-consumption-models/configuration-based-consumption-model). {% endhint %} **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 from our Seattle and San Francisco agents.
  • Create a DNS server synthetic test for [www.example.com](http://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 .
| | 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** ​ {% hint style="info" %} 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. {% endhint %} ​​​ | 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](https://nodejs.org/en/download). 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 ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.thousandeyes.com/product-documentation/integration-guides/thousandeyes-mcp-server.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.