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
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
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

# 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

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:

# 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:

# 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

• Cisco CX Cloud API Documentation
• Cisco API Console
• CX Cloud Portal
• Model Context Protocol

License

ISC