Cisco ThousandEyes MCP Server Setup

Prerequisites

Tool or access	Purpose	Verify
Bash and Python 3	Run bundled setup and validation helpers	bash --version && python3 --version
Required product/platform access	Inspect or configure the selected target	Complete the documented preflight
Credential files for live modes	Keep secrets out of chat	Verify paths only

Workflow Overview

┌───────────┐   ┌───────────────┐   ┌───────────────┐   ┌─────────────────┐
│ Preflight │ → │ Render/review │ → │ Apply/handoff │ → │ Validate evidence │
└───────────┘   └───────────────┘   └───────────────┘   └─────────────────┘

When to Activate

• Register the ThousandEyes MCP, set up TE in Cursor/Claude/Codex/VS Code/Kiro, configure the Cisco ThousandEyes Cursor plugin, or pair an AI assistant with TE.
• Preview and review the cisco thousandeyes mcp setup workflow before any live apply phase.
• Diagnose failed prerequisites, generated assets, configuration, or validation evidence.

Scope

Follow the documented read-only or render-first path whenever it is available. This skill does not imply permission to mutate live systems. Require explicit apply flags, protected credentials, and operator review for state changes.

Examples

Inspect the supported setup modes before selecting one:

bash skills/cisco-thousandeyes-mcp-setup/scripts/setup.sh --help

Expected output: usage, supported modes, and required arguments are displayed without changing the target environment.

Inspect validation modes before running completion checks:

bash skills/cisco-thousandeyes-mcp-setup/scripts/validate.sh --help

Expected output: offline, live, and completion options are displayed when the skill supports them; help exits without mutation.

Troubleshooting

Issue	Cause	Resolution
Preflight fails	A required tool or access path is missing	Resolve it before rendering or applying
Rendered assets are incomplete	Required non-secret inputs are absent	Complete intake and render again
Apply is blocked	Review, credentials, or explicit acceptance is missing	Use the documented handoff
Validation is incomplete	Live evidence is unavailable	Record the gap and keep completion open

This skill is agent-tooling only — it does not move telemetry. For TE → Splunk Observability Cloud wiring (OpenTelemetry stream, Integrations 2.0 APM connector, full TE asset lifecycle), use splunk-observability-thousandeyes-integration. For the Splunk Platform ta_cisco_thousandeyes add-on, use cisco-thousandeyes-setup.

Overview

Render per-client MCP configurations for the official ThousandEyes MCP Server at https://api.thousandeyes.com/mcp. Optionally apply the configurations into the user's actual Cursor / Claude Code / Codex / VS Code / AWS Kiro config locations.

Render-first by default. Automated --apply is supported for Codex with OAuth2; the other clients retain explicit reviewed manual merge handoffs.

Safety Rules

• Never ask for the ThousandEyes API token in conversation.
• Never pass the token on the command line or as an environment-variable prefix.
• Use --te-token-file for the Bearer header path; the renderer never reads the token file.
• Reject direct token flags (--te-token, --access-token, --token, --bearer-token, --api-token).
• Token files must be chmod 600. --apply runs a permission preflight and aborts with a chmod 600 <path> hint when looser. --allow-loose-token-perms overrides with a WARN.
• Cursor and VS Code configs use ${input:te-key} prompt-string patterns or environment variables, never inline tokens. Codex should use OAuth2 browser consent unless a client-side secret store can inject Bearer headers without argv exposure. Claude Code uses an OAuth-pair browser flow.
• --accept-te-mcp-write-tools records explicit operator acknowledgement for the write/Instant-Test group (Create/Update/Delete Synthetic Test, Run Instant Test, Deploy Template). It does not silently change client permissions; follow the rendered per-client approval guidance.

Primary Workflow

1. Decide which clients to register and which auth flow to use:

   • OAuth Bearer Token: simplest; one shared token file per client. Counts against the org-wide 240 req/min rate limit.
   • OAuth2 client: per-client OAuth2 flow with browser consent. Each OAuth2 client gets its own 240 req/min limit (recommended when multiple AI assistants share an org).

2. Render:

   bash skills/cisco-thousandeyes-mcp-setup/scripts/setup.sh \
     --render \
     --client cursor,claude,codex,vscode,kiro \
     --auth bearer \
     --te-token-file /tmp/te_api_token \
     --output-dir cisco-thousandeyes-mcp-rendered
   

3. Review cisco-thousandeyes-mcp-rendered/:

   • mcp/cursor.mcp.json
   • mcp/claude.mcp.json
   • mcp/codex-register-te-mcp.sh
   • mcp/vscode.mcp.json
   • mcp/kiro.mcp.json
   • mcp/README.md — per-client install instructions, rate-limit notes, unit-consumption warnings
   • metadata.json

4. Apply Codex OAuth2 registration only when explicitly requested. Cursor, Claude, VS Code, and Kiro remain reviewed manual config merges:

   bash skills/cisco-thousandeyes-mcp-setup/scripts/setup.sh \
     --apply \
     --client codex \
     --auth oauth2
   

Tool Group Gating

The official ThousandEyes MCP Server exposes two tool groups:

• Read-only tools (auto-allowed): List/Get Tests, List/Get Events, List/Get Alerts, Search Outages, Get Anomalies, Get Metrics, Get Service Map, Views Explanations, Endpoint Agent Metrics + Connected Device, Cloud/Enterprise Agents, Get Path / Full Path / BGP Test Results / BGP Route Details, Get Account Groups, Search/Deploy Templates (Search only).
• Write/Instant-Test tools (require explicit per-client approval; --accept-te-mcp-write-tools records operator acknowledgement): Create/Update/Delete Synthetic Test, Run Instant Test, Deploy Template.

Unit consumption. Run Instant Test consumes ThousandEyes units identically to scheduled tests. The rendered README always surfaces this warning, and --apply refuses to enable write tools without --accept-te-mcp-write-tools.

Hand-offs

• TE → Splunk Observability Cloud wiring → splunk-observability-thousandeyes-integration (OpenTelemetry stream, Integrations 2.0 APM connector, full TE asset lifecycle).
• Splunk Platform ta_cisco_thousandeyes add-on → cisco-thousandeyes-setup (HEC streaming inputs, OAuth device flow, indexes/sourcetypes).

Validation

bash skills/cisco-thousandeyes-mcp-setup/scripts/validate.sh

Static checks confirm every selected client has a renderable config; verifies no token material was written to any rendered file. Use --live after --apply to reach https://api.thousandeyes.com/mcp from each client config.

See reference.md for option details and references/clients.md for the per-client install matrix.