mcp-agentnex 0.1.0

MCP Server for AgentNEX - Bridge between NEXA AI and AgentNEX Backend

AgentNEX MCP Server

Model Context Protocol (MCP) server for AgentNEX - enabling AI assistants to manage and monitor devices through the AgentNEX platform.

Overview

This MCP server provides AI assistants (like NEXA) with secure access to AgentNEX device management capabilities. It supports both:

• HTTP REST API - For NEXA platform integration (cloud deployment)
• stdio (JSON-RPC) - For local MCP clients (Claude Desktop)

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    NEXA Platform / AI Assistant             │
└───────────────────────────┬─────────────────────────────────┘
                            │ HTTP REST API
┌───────────────────────────▼─────────────────────────────────┐
│                     MCP Server (FastAPI)                    │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │    Tools    │  │  Resources  │  │    Formatters       │  │
│  │  (7 tools)  │  │(3 resources)│  │ (telemetry/action)  │  │
│  └──────┬──────┘  └──────┬──────┘  └──────────┬──────────┘  │
│         └────────────────┼───────────────────┘              │
│                          │                                  │
│              ┌───────────▼───────────┐                      │
│              │    Backend Client     │                      │
│              └───────────┬───────────┘                      │
└──────────────────────────┼──────────────────────────────────┘
                           │ HTTP + API Key
┌──────────────────────────▼──────────────────────────────────┐
│                   AgentNEX Backend API                      │
└─────────────────────────────────────────────────────────────┘

Features

MCP Tools (7 available)

Tool	Description
get_device_telemetry	Get real-time CPU, memory, disk, and network metrics
get_device_processes	List running processes with resource usage
restart_process	Restart a specific process by name
kill_process	Terminate a process by name or PID
clear_cache	Clear application cache (Chrome, Edge, Teams, etc.)
flush_dns	Flush DNS resolver cache
restart_service	Restart a Windows service

MCP Resources (3 available)

Resource URI	Description
agentnex://devices/all	List of all registered devices
agentnex://devices/{id}/status	Device connection status
agentnex://devices/{id}/telemetry	Latest device telemetry data

Project Structure

agentnex-mcpserver/
├── app/
│   ├── client/
│   │   └── backend_client.py    # HTTP client for AgentNEX backend
│   ├── core/
│   │   ├── config.py            # Settings and configuration
│   │   └── exceptions.py        # Custom exceptions
│   ├── formatters/
│   │   ├── telemetry_formatter.py  # Format telemetry for AI
│   │   └── action_formatter.py     # Format action results
│   ├── resources/
│   │   ├── base.py              # Base resource class
│   │   └── device_resources.py  # Device resource implementations
│   ├── schemas/
│   │   ├── backend_schemas.py   # Backend API schemas
│   │   └── mcp_schemas.py       # MCP protocol schemas
│   ├── tools/
│   │   ├── base.py              # Base tool class
│   │   ├── telemetry_tools.py   # Telemetry tools
│   │   └── action_tools.py      # Action tools
│   ├── http_server.py           # FastAPI HTTP server (for NEXA)
│   ├── mcp_server.py            # stdio MCP server (for Claude Desktop)
│   └── main.py                  # Entry point
├── tests/
│   ├── test_api_key.py
│   ├── test_backend_integration.py
│   ├── test_backend_simple.py
│   ├── test_mcp_server.py
│   └── test_refactored_tools.py
├── .env                         # Environment variables (create from env.example)
├── env.example                  # Example environment configuration
├── requirements.txt             # Python dependencies
├── run_http_server.py           # Run HTTP server (for NEXA)
└── run_server.py                # Run stdio server (for Claude Desktop)

Installation

Prerequisites

• Python 3.11+
• AgentNEX Backend running and accessible
• Valid API key for AgentNEX Backend

Quick Start (PyPI Installation)

Install the MCP server directly from PyPI:

pip install mcp-agentnex

After installation, configure environment variables and run:

# Set required environment variables
export AGENTNEX_BACKEND_URL=https://your-backend-url.com
export AGENTNEX_API_KEY=your-api-key-here

# Run the MCP server
mcp-agentnex

For Claude Desktop Integration:

Add to your Claude Desktop configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/claude/claude_desktop_config.json

{
  "mcpServers": {
    "agentnex": {
      "command": "mcp-agentnex",
      "env": {
        "AGENTNEX_BACKEND_URL": "https://your-backend-url.com",
        "AGENTNEX_API_KEY": "your-api-key-here"
      }
    }
  }
}

Alternative Installation Methods

Option 1: Docker (Recommended for Production)

1. Configure environment:

   # Copy example config
   cp env.example .env
   
   # Edit .env with your settings
   nano .env
   

2. Build and run with Docker Compose:

   # Build and start
   docker-compose up --build -d
   
   # View logs
   docker-compose logs -f
   
   # Stop
   docker-compose down
   

3. Or build and run manually:

   # Build image
   docker build -t agentnex-mcp-server .
   
   # Run container
   docker run -d \
     --name agentnex-mcp-server \
     -p 8001:8001 \
     -e AGENTNEX_BACKEND_URL=http://host.docker.internal:8000/api \
     -e AGENTNEX_API_KEY=your-api-key \
     agentnex-mcp-server
   

Option 2: Development Installation from Source

1. Clone and navigate to the project:

   git clone https://github.com/ivedha-tech/agentnex-mcpserver.git
   cd agentnex-mcpserver
   

2. Create virtual environment:

   python -m venv venv
   
   # Windows
   .\venv\Scripts\Activate.ps1
   
   # Linux/Mac
   source venv/bin/activate
   

3. Install in development mode:

   # Install with dependencies
   pip install -e .
   
   # Or install with dev dependencies for testing
   pip install -e ".[dev]"
   

4. Configure environment:

   # Copy example config
   cp .env.example .env
   
   # Edit .env with your settings
   nano .env  # or use any text editor
   

5. Update .env file:

   AGENTNEX_BACKEND_URL=http://localhost:8000
   AGENTNEX_API_KEY=your-internal-api-key-here
   MCP_SERVER_PORT=8001
   

6. Run the server:

   # Run via CLI command
   mcp-agentnex
   
   # Or run directly with Python
   python -m app.mcp_server
   

Running the Server

Docker (Production)

# Start with Docker Compose
docker-compose up -d

# Check status
docker-compose ps

# View logs
docker-compose logs -f mcp-server

# Stop
docker-compose down

Local Development

HTTP Server (for NEXA Platform)

# Activate virtual environment first
.\venv\Scripts\Activate.ps1  # Windows
source venv/bin/activate      # Linux/Mac

# Run HTTP server
python run_http_server.py

Server will start at http://localhost:8001

stdio Server (for Claude Desktop)

If installed via PyPI:

mcp-agentnex

If running from source:

python run_server.py

API Endpoints

Health Check

GET /health
Response: {"status": "healthy", "backend_connected": true}

List Tools

GET /mcp/tools
Response: {"tools": [...]}

Call Tool

POST /mcp/tools/call
Content-Type: application/json

{
  "name": "get_device_telemetry",
  "arguments": {
    "device_id": "your-device-uuid"
  }
}

List Resources

GET /mcp/resources
Response: {"resources": [...]}

Read Resource

POST /mcp/resources/read
Content-Type: application/json

{
  "uri": "agentnex://devices/all"
}

Environment Variables

Variable	Description	Default
AGENTNEX_BACKEND_URL	AgentNEX backend API URL	http://localhost:8000
AGENTNEX_API_KEY	Internal API key for authentication	Required
MCP_SERVER_PORT	HTTP server port	8001
MCP_SERVER_NAME	Server name for MCP protocol	agentnex-mcp-server
MCP_SERVER_VERSION	Server version	1.0.0
LOG_LEVEL	Logging level	INFO
BACKEND_TIMEOUT	Backend request timeout (seconds)	30
BACKEND_RETRY_ATTEMPTS	Number of retry attempts	3

Testing

# Activate virtual environment
.\venv\Scripts\Activate.ps1

# Run specific test
python tests/test_api_key.py
python tests/test_mcp_server.py

# Run all tests with pytest
python -m pytest tests/ -v

NEXA Platform Integration

To integrate with NEXA platform:

1. Deploy HTTP server to a publicly accessible endpoint
2. Register the MCP server URL in NEXA
3. Configure agents to use the MCP tools

Example Tool Usage in NEXA Agent

Tool: get_device_telemetry
Input: {"device_id": "0682f172-cd1f-450a-97c9-bfc4ae56adcc"}
Output: Formatted telemetry data for AI consumption

Docker Deployment

Build Options

# Standard build
docker build -t agentnex-mcp-server .

# Build with specific tag
docker build -t agentnex-mcp-server:v1.0.0 .

# Build for production registry
docker build -t your-registry.com/agentnex-mcp-server:latest .
docker push your-registry.com/agentnex-mcp-server:latest

Environment Variables for Docker

Variable	Description	Default
AGENTNEX_BACKEND_URL	Backend URL (use host.docker.internal for local backend)	Required
AGENTNEX_API_KEY	Internal API key	Required
MCP_SERVER_PORT	Server port	8001
LOG_LEVEL	Log level (DEBUG, INFO, WARNING, ERROR)	INFO
LOG_FORMAT	Log format (json, text)	json

Docker Compose with Full Stack

To run MCP server alongside the backend:

# docker-compose.full.yml
version: '3.8'

services:
  backend:
    image: agentnex-backend:latest
    ports:
      - "8000:8000"
    networks:
      - agentnex-network

  mcp-server:
    image: agentnex-mcp-server:latest
    ports:
      - "8001:8001"
    environment:
      - AGENTNEX_BACKEND_URL=http://backend:8000/api
      - AGENTNEX_API_KEY=${AGENTNEX_API_KEY}
    depends_on:
      - backend
    networks:
      - agentnex-network

networks:
  agentnex-network:
    driver: bridge

Health Check

The container includes a health check endpoint:

# Check container health
docker inspect --format='{{.State.Health.Status}}' agentnex-mcp-server

# Manual health check
curl http://localhost:8001/health

Security

• API key authentication required for all backend requests
• CORS enabled for cross-origin requests
• Supports HTTPS for production deployment
• No sensitive data logged
• Container runs as non-root user
• Multi-stage build minimizes attack surface

Publishing to PyPI

To publish a new version to PyPI:

1. Update version in pyproject.toml
2. Update CHANGELOG.md with changes
3. Build the package:

   python -m pip install --upgrade build twine
   python -m build
   

4. Upload to PyPI:

   # Test PyPI (optional)
   python -m twine upload --repository testpypi dist/*
   
   # Production PyPI
   python -m twine upload dist/*
   

Contributing

Contributions are welcome! Please ensure:

• Code follows existing style and conventions
• All tests pass (pytest tests/)
• Documentation is updated for new features

Support

For issues and questions:

• Open an issue on GitHub
• Contact: AgentNEX Team at IVedha Technologies

License

MIT License

Copyright (c) 2025 IVedha Technologies - AgentNEX Team