mcp-agentnex 0.1.12

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 (8 Available)

Tool	Description
list_devices	List all registered devices for the account
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
AGENTNEX_MCP_SERVER_NAME	Server name for MCP protocol	agentnex-mcp-server
AGENTNEX_MCP_SERVER_VERSION	Server version	1.0.0
AGENTNEX_LOG_LEVEL	Logging level (DEBUG, INFO, WARNING, ERROR)	INFO
AGENTNEX_BACKEND_TIMEOUT	Backend request timeout (seconds)	30.0
AGENTNEX_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       │  │
│  │  (8 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

Test Locally Before PyPI

Use a clean venv and run the full pre-PyPI check (pytest, build, install from wheel, config with NEXA-like extra env):

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

pip install -e ".[dev]"
pip install requests            # optional, for test_http_api.py

# Run tests (excludes test_http_api if requests not installed)
python -m pytest tests/ -v --ignore=tests/test_http_api.py

# Config with NEXA/K8s extra env (extra="ignore")
python -m pytest tests/test_config_extra_env.py -v

# Build and verify install
pip install build
python -m build --outdir dist
pip install --force-reinstall dist/mcp_agentnex-*.whl
python -c "from app.mcp_server import cli; from app.core.config import settings; print('OK', settings.agentnex_mcp_server_name)"

# Simulate NEXA env: set postgres_*, openai_api_key, backend_base_url, then load config
# (Should not raise; Settings ignores extra env vars.)

Or run the script: python scripts/test_local_before_pypi.py (requires pip install requests for full test suite).

Test stdio (health, tools/list, tools/call)

From the repo root with venv activated and AGENTNEX_BACKEND_URL and AGENTNEX_API_KEY set:

# Windows
.\.venv\Scripts\Activate.ps1
$env:AGENTNEX_BACKEND_URL = "https://your-backend-url"
$env:AGENTNEX_API_KEY = "your-api-key"
python scripts/test_stdio_health_and_tools.py

# Linux/Mac
source .venv/bin/activate
export AGENTNEX_BACKEND_URL="https://your-backend-url"
export AGENTNEX_API_KEY="your-api-key"
python scripts/test_stdio_health_and_tools.py

This runs initialize (health), tools/list, and tools/call for list_devices over stdio. Expect: 1. Health (initialize): OK, 2. tools/list: OK, 3. tools/call list_devices: OK, then stdio test: all OK.

Publishing

To publish a new version to PyPI:

# 1. Update version in pyproject.toml and docs/CHANGELOG.md

# 2. (Optional) Run stdio test before release
python scripts/test_stdio_health_and_tools.py

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

# 4. Upload to PyPI (upload only the new version to avoid "File already exists" for old versions)
python -m twine upload dist/mcp_agentnex-0.1.3*   # replace 0.1.3 with your new version
# Or: Remove-Item dist\* -Force; python -m build; 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