Cisco MCP Pods Server

An MCP (Model Context Protocol) server that connects to the Cisco API Gateway pods endpoints. This server enables AI agents (like Claude Desktop or Webex Connect) to interact with pod management data, manage pod configurations, update pod credentials, and perform complete CRUD operations through natural language.

Deployment Modes

This server supports three transport modes:

1. stdio (Standard I/O) - For Claude Desktop

File: src/index.js
Communication: stdin/stdout
Usage: Runs locally as a child process
Perfect for: Claude Desktop application
Remote Access: ❌ Cannot be accessed remotely
Command: npm start

2. SSE (Server-Sent Events) - For Remote AI Agents

File: src/server-sse.js
Port: 1013
Endpoint: /CiscoMCPPods/sse
Usage: HTTP server with one-way streaming
Perfect for: Legacy remote AI agents
Remote Access: ✅ Can be deployed in the cloud
Command: npm run start:sse

3. Streamable HTTP - For Modern Remote AI Agents (Recommended)

File: src/server-http.js
Port: 1013
Endpoint: /CiscoMCPPods/mcp
Usage: HTTP server with bidirectional communication, session management, and resumability
Perfect for: WxConnect and modern AI agents that support the latest MCP spec
Remote Access: ✅ Can be deployed in the cloud
Features: Session-based, event replay, connection resumability
Command: npm run start:http

Which Transport Should I Use?

Scenario	Recommended Transport	Why
Claude Desktop (local)	stdio	Fastest, most efficient for local use
WxConnect (cloud)	Streamable HTTP	Modern protocol with resumability and better error handling
Legacy AI agents	SSE	Older protocol, widely supported
Testing locally	Any	All modes support local testing

Features

Tools (7 available)

get_pod_keyword - Get the pod keyword/password record
update_pod_keyword - Update the pod keyword/password with a new value
get_all_pods - Get all pods from a specific collection (ciscolivepods, coelabpods, etc.)
get_pod_by_number - Get a specific pod by its number from a collection
create_pod - Create new pod records in a collection
update_pod - Update existing pod information (status, credentials, test data, etc.)
delete_pod - Delete pod records from a collection

Resources (2 available)

pods://keyword - Access the current pod keyword configuration
pods://config - View current API configuration and connection status

Prerequisites

Node.js >= 18.0.0 (for built-in fetch support and ES modules)
Cisco API Gateway - Remote: http://apigateway.cxocoe.us or Local: http://localhost:3002
Valid API Key or JWT token for authentication

Installation

# Clone or navigate to the project directory
cd CiscoMCPPods

# Install dependencies
npm install

Configuration

Environment Variables

Copy the example environment file and edit it:

cp .env.example .env

Edit .env with your settings:

# Cisco API Gateway Configuration
API_BASE_URL=http://apigateway.cxocoe.us

# Authentication (API Key recommended)
API_KEY_PODS=f42a9c8e3d7b1f6a2c5e8d4b9f3a6c1e7b5d2f9a8c4e1b6d3f7a2c5e8b1d4f9a3c6
AUTH_MODE=apikey

# MCP Server Configuration (for SSE/HTTP transport modes only)
SERVER_PORT=1013
SERVER_PATH=/CiscoMCPPods

# Public hostname (for deployment)
PUBLIC_HOSTNAME=ciscomcppods.cxocoe.us

# MCP Server Authentication
# API key required for client connections to this MCP server
# Generate a secure random key: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
MCP_API_KEY=your-mcp-api-key-here

# Anthropic API Key (optional - for test-mcp-client.js only)
# Required for the interactive MCP client tester with Anthropic AI integration
# Get your key from: https://console.anthropic.com/
ANTHROPIC_API_KEY=sk-ant-api03-your-key-here

Important:

The API_BASE_URL points to your Cisco API Gateway (backend), not the MCP server itself.
The MCP_API_KEY is used to authenticate clients connecting to this MCP server (not the API Gateway).

Usage: Claude Desktop (Local)

Claude Desktop is a desktop application that can run MCP servers locally on your computer.

Step 1: Locate Configuration File

On macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

On Windows:

%APPDATA%/Claude/claude_desktop_config.json

Step 2: Edit Configuration

Open the file and add your MCP server configuration:

{
  "mcpServers": {
    "cisco-pods": {
      "command": "/Users/YOUR_USERNAME/.nvm/versions/node/v18.20.8/bin/node",
      "args": [
        "/FULL/PATH/TO/CiscoMCPPods/src/index.js"
      ]
    }
  }
}

Important Notes:

Replace /Users/YOUR_USERNAME/ with your actual user path
Replace /FULL/PATH/TO/ with the actual path to your project
Use full absolute paths, not relative paths
Point to Node.js 18+ (not the system default if it's older)
Use src/index.js for stdio mode, NOT src/server-sse.js or src/server-http.js

Step 3: Find Your Node.js Path

If using nvm:

which node
# or
nvm which 18

If using system Node.js:

which node

Use the full path in the config file.

Step 4: Restart Claude Desktop

Quit Claude Desktop completely (Cmd+Q on Mac, or close completely on Windows)
Reopen Claude Desktop
The MCP server will start automatically

Step 5: Verify Connection

In Claude Desktop, try these prompts:

What tools do you have access to?

Get all pods from the ciscolivepods collection

Get pod keyword configuration

If connected successfully, AI agent will list the 7 pods tools and be able to execute them.

Troubleshooting Claude Desktop

If you see "Server disconnected":

Check the logs:

tail -f ~/Library/Logs/Claude/mcp-server-cisco-pods.log

Common issues:
- Wrong Node.js version: Must be 18+, check logs for syntax errors
- .env not loading: Check that .env file exists in project root
- API key missing: Check logs for "API_KEY_PODS is not configured"
- Path errors: Make sure all paths in config are absolute, not relative

Verify Node version:

/path/to/your/node --version
# Should output v18.x.x or higher

Usage: Cloud Deployment (WxConnect)

Deploy the server to the cloud for remote AI agents like Webex Connect.

Step 1: Choose Your Transport Mode

Streamable HTTP (Recommended for WxConnect):

Modern protocol with session management
Automatic reconnection and event replay
Better error handling
Use npm run start:http

SSE (Legacy):

Simpler protocol
One-way streaming
Use npm run start:sse

For this guide, we'll use Streamable HTTP as it's the recommended approach.

Step 2: Prepare for Deployment

Update .env for production:

API_BASE_URL=http://apigateway.cxocoe.us
API_KEY_PODS=your-production-api-key
AUTH_MODE=apikey
SERVER_PORT=3010
SERVER_PATH=/CiscoMCPPods

Ensure .gitignore excludes .env:

# Check .gitignore includes:
.env
node_modules/

Step 3: Deploy to Your Server

Via SCP/SFTP:

# Copy project to server
scp -r CiscoMCPPods user@your-server:/path/to/apps/

Via Git:

# On your server
cd /path/to/apps
git clone your-repo-url CiscoMCPPods
cd CiscoMCPPods
npm install
cp .env.example .env
nano .env  # Edit with your settings

Step 4: Run Server

For testing:

# Streamable HTTP (Recommended)
npm run start:http

# OR SSE (Legacy)
npm run start:sse

For production (with PM2):

# Install PM2 globally
npm install -g pm2

# Start server with Streamable HTTP
pm2 start npm --name "mcp-pods-http" -- run start:http

# OR with SSE
pm2 start npm --name "mcp-pods-sse" -- run start:sse

# Save PM2 process list
pm2 save

# Set PM2 to start on boot
pm2 startup

For production (with systemd):

Create /etc/systemd/system/mcp-pods.service:

[Unit]
Description=MCP Pods Server (Streamable HTTP)
After=network.target

[Service]
Type=simple
User=your-user
WorkingDirectory=/path/to/CiscoMCPPods
ExecStart=/usr/bin/node src/server-http.js
Restart=always
Environment=NODE_ENV=production

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl enable mcp-pods
sudo systemctl start mcp-pods
sudo systemctl status mcp-pods

Step 5: Configure NGINX Reverse Proxy (Optional)

For Streamable HTTP, create NGINX configuration:

server {
    listen 80;
    server_name ciscomcppods.cxocoe.us ciscomcppods.cxocoe.us ciscomcphealth.cxocoe.us ciscomcpinsurance.cxocoe.us;

    # Pods MCP Server (Streamable HTTP)
    location /CiscoMCPPods/ {
        proxy_pass http://localhost:1013;
        proxy_http_version 1.1;

        # Required for Streamable HTTP
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header Mcp-Session-Id $http_mcp_session_id;
        proxy_set_header Last-Event-Id $http_last_event_id;

        # Required for API key authentication
        proxy_set_header X-API-Key $http_x_api_key;

        # Timeouts for long-lived connections
        proxy_read_timeout 3600s;
        proxy_send_timeout 3600s;
        proxy_connect_timeout 75s;

        # SSE specific
        proxy_buffering off;
        proxy_cache off;
        chunked_transfer_encoding off;
    }
}

Enable the site:

sudo ln -s /etc/nginx/sites-available/mcp-pods /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

Step 6: Test Cloud Deployment

Test health endpoint:

curl http://ciscomcppods.cxocoe.us/CiscoMCPPods/health

Expected response:

{
  "status": "healthy",
  "service": "cisco-mcp-pods",
  "version": "1.0.0",
  "transport": "streamable-http",
  "apiBaseUrl": "http://apigateway.cxocoe.us",
  "timestamp": "2025-10-18T00:00:00.000Z"
}

Test MCP endpoint (with authentication):

curl -X POST http://ciscomcppods.cxocoe.us/CiscoMCPPods/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "X-API-Key: your-mcp-api-key" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": {"name": "test-client", "version": "1.0.0"}
    }
  }'

Step 7: Register with WxConnect

Once deployed, register your MCP server with Webex Connect:

For Streamable HTTP:

Endpoint URL: http://ciscomcppods.cxocoe.us/CiscoMCPPods/mcp
Transport Type: Streamable HTTP
Authentication: Include X-API-Key header with your MCP API key

For SSE (Legacy):

Endpoint URL: http://ciscomcppods.cxocoe.us/CiscoMCPPods/sse
Transport Type: SSE (Server-Sent Events)
Authentication: Include X-API-Key header with your MCP API key

WxConnect will validate the connection and start using your MCP server.

Testing

Local Testing (stdio mode)

Use Claude Desktop - see Usage: Claude Desktop

Cloud Testing (HTTP/SSE modes)

1. Health Check

curl http://localhost:1013/CiscoMCPPods/health

2. Server Info

curl http://localhost:1013/

3. Streamable HTTP Connection Test

# Initialize session
curl -X POST http://localhost:1013/CiscoMCPPods/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": {"name": "test", "version": "1.0.0"}
    }
  }'

4. SSE Connection Test

curl -N http://localhost:1013/CiscoMCPPods/sse

5. Automated Test Script

Run the included test script:

npm test

This comprehensive test suite includes:

Server status check
Health endpoint validation
SSE connection test
Message endpoint test
Beautiful colored output with test results

6. Interactive MCP Client with Anthropic AI (NEW!)

Test your MCP server end-to-end with a full AI agent integration:

npm run test:client

This interactive test tool:

✅ Connects to your production MCP server with X-API-Key authentication
✅ Integrates with Anthropic AI to demonstrate real agent-tool interaction
✅ Provides an interactive chat interface - ask questions in natural language
✅ AI agent automatically discovers and uses your MCP tools
✅ See real-time tool execution and results
✅ Validates the complete MCP workflow before WxConnect integration

Requirements:

ANTHROPIC_API_KEY in your .env file (get one at https://console.anthropic.com/)
Production MCP server running (or use localhost for testing)

Example session:

You: Show me all pods from ciscolivepods collection
[AI agent uses get_all_pods tool and displays results]

You: Get pod number 1 from ciscolivepods
[AI agent uses get_pod_by_number tool with the collection and number]

You: What's the pod keyword?
[AI agent uses get_pod_keyword tool]

You: quit
[Exits the interactive session]

This is the closest simulation to how WxConnect will use your MCP server!

7. MCP Inspector (Official Tool)

For Streamable HTTP:

npx @modelcontextprotocol/inspector http http://localhost:1013/CiscoMCPPods/mcp

For SSE:

npx @modelcontextprotocol/inspector sse http://localhost:1013/CiscoMCPPods/sse

This opens a web UI where you can:

View all available tools
Test each tool with different parameters
View resources
See JSON-RPC message flow
Monitor session state (for Streamable HTTP)

API Endpoints Mapping

This MCP server connects to the following Cisco API Gateway endpoints:

MCP Tool	API Endpoint	Method
get_pod_keyword	`/api/v2/pods/keyword`	GET
update_pod_keyword	`/api/v2/pods/keyword`	PATCH
get_all_pods	`/api/v2/pods/{collection}`	GET
get_pod_by_number	`/api/v2/pods/{collection}/{number}`	GET
create_pod	`/api/v2/pods/{collection}`	POST
update_pod	`/api/v2/pods/{collection}/{number}`	PATCH
delete_pod	`/api/v2/pods/{collection}/{number}`	DELETE

Project Structure

CiscoMCPPods/
├── src/
│   ├── index.js          # MCP server (stdio mode for Claude Desktop)
│   ├── server-sse.js     # MCP server (SSE mode for legacy AI agents)
│   ├── server-http.js    # MCP server (Streamable HTTP for modern AI agents)
│   ├── podsClient.js     # API client for pods endpoints
│   └── config.js         # Configuration management
├── .env                  # Environment variables (not in git)
├── .env.example          # Environment template
├── test-server.js        # Comprehensive test suite
├── nginx.conf.example    # NGINX reverse proxy configuration
├── package.json          # Project configuration
├── .gitignore           # Git ignore rules
└── README.md            # Documentation

Troubleshooting

Claude Desktop Issues

Server Disconnected:

# Check logs
tail -f ~/Library/Logs/Claude/mcp-server-cisco-pods.log

# Common fixes:
# 1. Use Node.js 18+ (check path in config)
# 2. Use absolute paths in claude_desktop_config.json
# 3. Ensure .env file exists with API_KEY_PODS

API Authentication Errors:

Check .env file exists in project root
Verify API_KEY_PODS is set correctly
Check API_BASE_URL points to Cisco API Gateway

Cloud Deployment Issues

Port Already in Use:

# Find what's using port 1013
lsof -i :1013
# or
netstat -tulpn | grep 1013

# Kill the process or use different port

Health Check Fails:

# Check if server is running
ps aux | grep server-http.js

# Check server logs
journalctl -u mcp-pods -f  # if using systemd
pm2 logs mcp-pods          # if using PM2

Session Issues (Streamable HTTP):

Verify Mcp-Session-Id header is being sent correctly
Check server logs for session initialization messages
Ensure NGINX passes through session headers

NGINX Issues:

# Test NGINX config
sudo nginx -t

# Check NGINX error log
sudo tail -f /var/log/nginx/error.log

# Restart NGINX
sudo systemctl restart nginx

Firewall Issues:

# Allow port 3010 (if not using NGINX)
sudo ufw allow 3010/tcp

# Allow port 80 (if using NGINX)
sudo ufw allow 80/tcp

API Gateway Connection Issues

Cannot reach API Gateway:

Verify API_BASE_URL in .env

Test connection manually:

curl http://apigateway.cxocoe.us/api/v2/pods/keyword \
  -H "x-api-key: YOUR_API_KEY"

Authentication Failures:

Verify API key matches your Cisco API Gateway configuration
Check if API key has 'pods' permissions
Try with master API key for testing

Running Multiple MCP Servers

To run Pods, Healthcare, Insurance, and Retail MCP servers together:

Each server has its own directory:

CiscoMCPPods/       (Port 1013)
CiscoMCPPods/     (Port 3010)
CiscoMCPHealthcare/ (Port 3011)
CiscoMCPInsurance/  (Port 3012)

Each has unique configuration in .env:

# Pods
SERVER_PORT=1013
SERVER_PATH=/CiscoMCPPods
API_KEY_PODS=f42a9c8e3d7b1f6a2c5e8d4b9f3a6c1e7b5d2f9a8c4e1b6d3f7a2c5e8b1d4f9a3c6

# Healthcare
SERVER_PORT=3011
SERVER_PATH=/CiscoMCPHealthcare
API_KEY_HEALTH=b81108cab4b0d0db3beccc9c2a71888d43d4d7acddc7b9024ee715c15474a856

# Insurance
SERVER_PORT=3012
SERVER_PATH=/CiscoMCPInsurance
API_KEY_INSURANCE=e64d49daa3709f4ebaa60d6cd0513162b3216860961315a34646e99666900b0a

Update NGINX to proxy all four (add location blocks for each)
Register each with WxConnect (with API key authentication):
- Pods: http://ciscomcppods.cxocoe.us/CiscoMCPPods/mcp
- Retail: http://ciscomcppods.cxocoe.us/CiscoMCPPods/mcp
- Healthcare: http://ciscomcphealth.cxocoe.us/CiscoMCPHealthcare/mcp
- Insurance: http://ciscomcpinsurance.cxocoe.us/CiscoMCPInsurance/mcp
Important: Include X-API-Key header with each server's unique API key

Security Considerations

For Production Deployment:

Use HTTPS - Update NGINX config with SSL certificates
Firewall - Only expose necessary ports (1013 for Pods)
API Keys - Store in environment variables, never commit to git
NGINX - Use as reverse proxy instead of exposing Node.js directly
Rate Limiting - Configure in NGINX
Monitoring - Set up health check monitoring
Session Security - For Streamable HTTP, consider implementing session timeout policies

Transport Comparison

Feature	stdio	SSE	Streamable HTTP
Local Use	✅ Best	❌ Not needed	❌ Not needed
Remote Use	❌ No	✅ Yes	✅ Yes
Session Management	N/A	❌ No	✅ Yes
Resumability	N/A	❌ No	✅ Yes
Event Replay	N/A	❌ No	✅ Yes
Bidirectional	✅ Yes	❌ One-way	✅ Yes
Connection Recovery	N/A	⚠️ Manual	✅ Automatic
WxConnect Support	❌ No	✅ Yes (Legacy)	✅ Yes (Recommended)

Author

Rue Green Customer Care Architect and Developer Cisco Systems, INC.

License

MIT

Support

For issues or questions:

Check logs (Claude Desktop or server logs)
Verify .env configuration
Test API Gateway connection directly
Review error messages for specific issues
Run npm test to verify server functionality

Version: 1.0.0 Last Updated: October 2025

Name		Name	Last commit message	Last commit date
Latest commit History 10 Commits
.claude		.claude
POSTMAN Collections		POSTMAN Collections
src		src
.ai-preferences		.ai-preferences
.env.example		.env.example
.gitignore		.gitignore
ARCHITECTURE.md		ARCHITECTURE.md
README.md		README.md
debug-init.js		debug-init.js
nginx.conf.example		nginx.conf.example
package-lock.json		package-lock.json
package.json		package.json
test-all-servers.js		test-all-servers.js
test-mcp-client.js		test-mcp-client.js
test-mcp-sse.js		test-mcp-sse.js
test-public-mcp.js		test-public-mcp.js
test-server.js		test-server.js
test-sse-client.js		test-sse-client.js
test-sse-manual.js		test-sse-manual.js

ruegreen/CiscoMCPPods

Folders and files

Latest commit

History

Repository files navigation