mcp-agentnex 0.1.1

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

AgentNEX MCP Server

A Model Context Protocol (MCP) server that provides AI assistants with secure access to AgentNEX device management and monitoring capabilities.

Overview

The AgentNEX MCP Server enables AI assistants to interact with the AgentNEX platform through the Model Context Protocol. It provides tools for device management, telemetry monitoring, and system actions via stdio (JSON-RPC) transport.

Features

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, Outlook)
flush_dns	Flush DNS resolver cache
restart_service	Restart a Windows service

Resources (3 Available)

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

Installation

From PyPI (Recommended)

pip install mcp-agentnex

From Source

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

Quick Start

1. Set Environment Variables

export AGENTNEX_BACKEND_URL=<your-backend-url>
export AGENTNEX_API_KEY=<your-api-key>

2. Run the Server

mcp-agentnex

The server runs in stdio mode and communicates via JSON-RPC over stdin/stdout.

Configuration

Required Environment Variables

Variable	Description
AGENTNEX_BACKEND_URL	AgentNEX backend API endpoint
AGENTNEX_API_KEY	API key for backend authentication

Optional Environment Variables

Variable	Description	Default
MCP_SERVER_NAME	Server name for MCP protocol	agentnex-mcp-server
MCP_SERVER_VERSION	Server version	1.0.0
LOG_LEVEL	Logging level (DEBUG, INFO, WARNING, ERROR)	INFO
BACKEND_TIMEOUT	Backend request timeout (seconds)	30.0
BACKEND_RETRY_ATTEMPTS	Number of retry attempts	3

Usage

MCP Protocol Communication

The server uses stdio transport and follows the Model Context Protocol specification:

Initialize Connection

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{}}}

List Available Tools

{"jsonrpc":"2.0","id":2,"method":"tools/list"}

Call a Tool

{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get_device_telemetry","arguments":{"device_id":"device-uuid"}}}

List Available Resources

{"jsonrpc":"2.0","id":4,"method":"resources/list"}

Read a Resource

{"jsonrpc":"2.0","id":5,"method":"resources/read","params":{"uri":"agentnex://devices/all"}}

Integration

With AI Platforms

AI platforms can integrate with this MCP server by:

1. Installing the package: pip install mcp-agentnex
2. Configuring backend URL and API key as environment variables
3. Starting the server as a subprocess
4. Communicating via JSON-RPC messages over stdin/stdout

Example Integration Code

import subprocess
import json

# Start the MCP server
proc = subprocess.Popen(
    ['mcp-agentnex'],
    stdin=subprocess.PIPE,
    stdout=subprocess.PIPE,
    stderr=subprocess.PIPE,
    env={
        'AGENTNEX_BACKEND_URL': 'https://your-backend-url',
        'AGENTNEX_API_KEY': 'your-api-key'
    }
)

# Send initialize request
request = {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {"protocolVersion": "2024-11-05", "capabilities": {}}
}
proc.stdin.write(json.dumps(request).encode() + b'\n')
proc.stdin.flush()

# Read response
response = proc.stdout.readline()
print(json.loads(response))

Architecture

┌─────────────────────────────────────────────────────────────┐
│                      AI Platform / Client                   │
└───────────────────────────┬─────────────────────────────────┘
                            │ stdio (JSON-RPC)
                            │ stdin/stdout
┌───────────────────────────▼─────────────────────────────────┐
│                  MCP Server (mcp-agentnex)                  │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │    Tools    │  │  Resources  │  │    Formatters       │  │
│  │  (7 tools)  │  │(3 resources)│  │ (telemetry/action)  │  │
│  └──────┬──────┘  └──────┬──────┘  └──────────┬──────────┘  │
│         └────────────────┼───────────────────┘              │
│                          │                                  │
│              ┌───────────▼───────────┐                      │
│              │    Backend Client     │                      │
│              └───────────┬───────────┘                      │
└──────────────────────────┼──────────────────────────────────┘
                           │ HTTP + API Key
┌──────────────────────────▼──────────────────────────────────┐
│                   AgentNEX Backend API                      │
└─────────────────────────────────────────────────────────────┘

Security

• API Key Authentication: All backend requests require valid API key
• Subprocess Isolation: Server runs as isolated subprocess
• No Network Exposure: stdio transport eliminates network attack surface
• Input Validation: All tool arguments are validated before execution
• Secure Communication: HTTPS support for backend API calls
• No Sensitive Logging: API keys and credentials are never logged

Development

Setup Development Environment

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

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

# Install in development mode
pip install -e ".[dev]"

# Configure environment
cp .env.example .env
# Edit .env with your settings

Run Tests

# Activate virtual environment
source venv/bin/activate

# Run tests
python -m pytest tests/ -v

Publishing

To publish a new version to PyPI:

# Update version in pyproject.toml
# Update CHANGELOG.md

# Build the package
python -m pip install --upgrade build twine
python -m build

# Upload to PyPI
python -m twine upload dist/*

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Support

For issues and questions:

• GitHub Issues: https://github.com/ivedha-tech/agentnex-mcpserver/issues
• Contact: AgentNEX Team at IVedha Technologies

License

MIT License - Copyright (c) 2025 IVedha Technologies

Links

• PyPI: https://pypi.org/project/mcp-agentnex/
• GitHub: https://github.com/ivedha-tech/agentnex-mcpserver
• Documentation: https://github.com/ivedha-tech/agentnex-mcpserver/wiki