Cisco CX Cloud MCP Server
A Model Context Protocol (MCP) server that provides natural language access to Cisco CX Cloud APIs. Query your Cisco inventory, contracts, alerts, and more using conversational language through Claude or other MCP-compatible clients.
Features
This MCP server provides 10 tools to access Cisco CX Cloud data:
Customer Management
- get_customer_accounts - Get all accessible CX Cloud customer accounts and IDs
Inventory Management
- get_hardware_inventory - Get hardware inventory for a customer
- get_network_elements - Get network elements and devices
Contract Management
- get_contracts - Get all contracts for a customer
- get_covered_assets - Get assets covered by contracts
- get_uncovered_assets - Identify coverage gaps
Product Alerts
- get_field_notices - Get field notices and bulletins
- get_hardware_eol - Get hardware end-of-life information
- get_software_eol - Get software end-of-life information
- get_security_advisories - Get security advisories and alerts
Prerequisites
- Cisco.com Account - You need a Cisco.com account
- CX Cloud Access - You must have a role in at least one CX Cloud account at https://cx.cisco.com
- API Credentials - Register an application to get OAuth credentials
Setup Instructions
Step 1: Register Your Application
- Go to Cisco API Console
- Sign in with your Cisco.com credentials
- Click "My Apps & Keys" → "Register a New App"
- Choose "Service" as application type
- Select "Client Credentials" as grant type
- Add these CX Cloud API resources:
- Alerts v2
- Contracts v2
- Customer v2
- Inventory v2
- Accept terms and complete registration
- Save your Client ID and Client Secret
Step 2: Associate Credentials with CX Cloud
- Log into CX Cloud
- Navigate to Profile & Account → Manage Profile → API tab
- Enter your Client ID from Step 1
Note: There may be up to 10 minutes delay before you can use the API after first-time setup.
Step 3: Install and Configure
# Install dependencies
npm install
# Create .env file from example
cp .env.example .env
# Edit .env and add your credentials
# CISCO_CLIENT_ID=your_client_id_here
# CISCO_CLIENT_SECRET=your_client_secret_here
Step 4: Build the Server
npm run build
Running the Server
Development mode (with auto-reload)
npm run dev
Production mode
npm start
Configuration for Claude Desktop
To use this MCP server with Claude Desktop, add the following to your configuration file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"cisco-cx-cloud": {
"command": "node",
"args": [
"/absolute/path/to/cisco-cx-cloud-mcp/dist/index.js"
],
"env": {
"CISCO_CLIENT_ID": "your_client_id_here",
"CISCO_CLIENT_SECRET": "your_client_secret_here"
}
}
}
}
Important: Replace /absolute/path/to/cisco-cx-cloud-mcp/ with your actual installation path and add your real credentials.
After configuration, restart Claude Desktop.
Usage Examples
Once configured, you can ask Claude questions like:
Getting Started
- "What customer accounts do I have access to?"
- "Show me my customer IDs"
Inventory Queries
- "What hardware inventory do we have for customer XYZ?"
- "List all network elements for my customer"
- "Show me all Cisco devices in our inventory"
Contract Management
- "What contracts do we have?"
- "Are there any assets without contract coverage?"
- "Which devices are covered by support contracts?"
Alerts and Compliance
- "Are there any security advisories I should know about?"
- "What hardware is reaching end-of-life?"
- "Show me all field notices for customer ABC"
- "Which software versions are being deprecated?"
Complex Queries
- "Find all uncovered assets and check if any have security advisories"
- "Show me hardware that's both EOL and not covered by contracts"
- "Compare our inventory against active contracts"
How It Works
- OAuth Authentication: The server automatically handles OAuth 2.0 authentication using client credentials
- Token Management: Access tokens are cached and automatically refreshed when expired
- API Calls: Natural language requests are translated to appropriate API calls
- Data Formatting: Responses are formatted in easy-to-read JSON
- Logging: Comprehensive logging tracks all operations for debugging and monitoring
Logging
The server includes detailed logging capabilities:
Log Levels
Configure logging via the LOG_LEVEL environment variable:
- ERROR - Only errors (authentication failures, API errors)
- WARN - Warnings and errors
- INFO - General information, tool invocations, API requests (default)
- DEBUG - Detailed debugging including request/response details, token management
Configuration
Edit your .env file:
# Set log level (ERROR, WARN, INFO, DEBUG)
LOG_LEVEL=DEBUG
# Enable file logging
LOG_TO_FILE=true
# Set log directory (default: ./logs)
LOG_DIR=./logs
Log Output
Console Logs (stderr):
- When running via Claude Desktop: Check
~/Library/Logs/Claude/mcp*.log(macOS) - When running manually: Logs appear in terminal
File Logs (optional):
- Enable with
LOG_TO_FILE=true - Files are created in the
LOG_DIRdirectory - Named by date:
mcp-server-2024-12-01.log
What Gets Logged
INFO level:
- Server startup/shutdown
- Tool invocations
- Authentication events
- Tool completion with duration
DEBUG level (includes INFO plus):
- Environment configuration
- OAuth token details (sanitized)
- Full API request/response cycles
- Request timing and performance metrics
Example DEBUG output:
[2024-12-01T00:00:00.000Z] [INFO] Cisco CX Cloud MCP Server starting...
[2024-12-01T00:00:00.001Z] [DEBUG] Environment loaded
{
"logLevel": "DEBUG",
"hasClientId": true,
"hasClientSecret": true
}
[2024-12-01T00:00:01.000Z] [INFO] Tool invoked: get_customer_accounts
[2024-12-01T00:00:01.100Z] [DEBUG] API Request: GET https://apix.cisco.com/...
[2024-12-01T00:00:01.500Z] [DEBUG] API call completed in 400ms
[2024-12-01T00:00:01.501Z] [INFO] Tool SUCCESS: get_customer_accounts
{
"duration": "500ms"
}
API Rate Limits
The Cisco CX Cloud API has rate limits. The server handles:
- Automatic token refresh (tokens expire after 1 hour)
- Error handling for API failures
- Proper authentication header management
- Request/response logging for debugging
Project Structure
cisco-cx-cloud-mcp/
├── src/
│ ├── index.ts # Main MCP server
│ ├── auth.ts # OAuth authentication client
│ └── logger.ts # Logging utility
├── dist/ # Compiled JavaScript (generated)
├── logs/ # Log files (if LOG_TO_FILE=true)
├── .env.example # Environment template
├── .env # Your credentials (git-ignored)
├── package.json # Project configuration
├── tsconfig.json # TypeScript configuration
└── README.md # This file
Troubleshooting
Authentication Errors
- Verify your Client ID and Secret are correct
- Ensure you've associated the Client ID with your CX Cloud profile
- Wait 10 minutes after first-time setup
- Check logs: Set
LOG_LEVEL=DEBUGto see detailed OAuth flow
No Data Returned
- Confirm you have access to CX Cloud accounts at https://cx.cisco.com
- Verify your user has proper roles assigned
- Check that you're using the correct customer ID
- Check logs: Look for API response codes and error messages
API Errors
- Check that all required API resources are enabled in API Console
- Ensure your credentials haven't expired
- Verify network connectivity
- Check logs: Review full error stack traces with
LOG_LEVEL=DEBUG
Debugging Tips
Enable debug logging:
# In .env file
LOG_LEVEL=DEBUG
LOG_TO_FILE=true
View logs in real-time:
# macOS - Claude Desktop logs
tail -f ~/Library/Logs/Claude/mcp*.log
# Or if LOG_TO_FILE=true
tail -f ./logs/mcp-server-*.log
Common log messages:
"Access token obtained successfully"- Authentication working"Tool invoked: get_customer_accounts"- Tool called by Claude"API call completed in Xms"- Request performance"Failed to obtain access token"- Check credentials
Resources
License
ISC
