# 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). ## Usage 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 %} ### 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](https://1112912342-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M4QARF6s57qxMrOHDTZ%2Fuploads%2Fgit-blob-c0bc55c0fe49eb8b9f60fac7afc1638c0657a5dc%2Fclaude-connector-1.png?alt=media) 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.
| **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.
| ​​​​ **AI-Powered Skills**​ | Tool | Description | Sample Prompts | | ------------------ | ------------------------------------------------- | --------------------------------------------------------------------------------------------------- | | Views Explanations | Explain specific test results and visualizations. |
  • Explain the network path for test at time/date.
| ​ **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?
| | 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 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.
| ​ **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.
| **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?
| ​​ **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?
| **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.
| ## 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 ```