Cisco CX Cloud MCP Server

# 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 1. **Cisco.com Account** - You need a Cisco.com account 2. **CX Cloud Access** - You must have a role in at least one CX Cloud account at https://cx.cisco.com 3. **API Credentials** - Register an application to get OAuth credentials ## Setup Instructions ### Step 1: Register Your Application 1. Go to [Cisco API Console](https://apiconsole.cisco.com) 2. Sign in with your Cisco.com credentials 3. Click "My Apps & Keys" → "Register a New App" 4. Choose "Service" as application type 5. Select "Client Credentials" as grant type 6. Add these CX Cloud API resources: - Alerts v2 - Contracts v2 - Customer v2 - Inventory v2 7. Accept terms and complete registration 8. Save your **Client ID** and **Client Secret** ### Step 2: Associate Credentials with CX Cloud 1. Log into [CX Cloud](https://cx.cisco.com) 2. Navigate to **Profile & Account** → **Manage Profile** → **API** tab 3. 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 ```bash # 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 ```bash npm run build ``` ## Running the Server ### Development mode (with auto-reload) ```bash npm run dev ``` ### Production mode ```bash 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` ```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 1. **OAuth Authentication**: The server automatically handles OAuth 2.0 authentication using client credentials 2. **Token Management**: Access tokens are cached and automatically refreshed when expired 3. **API Calls**: Natural language requests are translated to appropriate API calls 4. **Data Formatting**: Responses are formatted in easy-to-read JSON 5. **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: ```bash # 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_DIR` directory - 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=DEBUG` to 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:** ```bash # In .env file LOG_LEVEL=DEBUG LOG_TO_FILE=true ``` **View logs in real-time:** ```bash # 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 - [Cisco CX Cloud API Documentation](https://developer.cisco.com/docs/cx-cloud/) - [Cisco API Console](https://apiconsole.cisco.com) - [CX Cloud Portal](https://cx.cisco.com) - [Model Context Protocol](https://modelcontextprotocol.io) ## License ISC