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

License

ISC

Cisco CX Cloud MCP Server

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

License

ISC