MCP Integration

ai_nn_controller automatically generates MCP (Model Context Protocol) tools for AI agent integration, enabling AI agents such as Claude to discover and control network equipment without any extra configuration.

Overview

MCP tools are auto-generated from:

Application control_functions → Control tools
Application read_measurements → Measurement tools
Application state management → State tools
@agent_controlled decorated methods → Agent-controlled tools

MCP Endpoints

Server Info

List All Tools

List Tools by App

Call Tool

MCP JSON-RPC

Server-Sent Events

Auto-Generated Tools

For each @aic_app, the following tools are generated:

Control Tools

One tool per command in control_functions:

Name: {AppName}_{command_name}
Example: NetworkApp1_set_gain
Schema: From command registry schema

Measurement Tool

If app has read_measurements:

Name: {AppName}_get_measurements
Schema: Optional node_id filter

State Tools

For every app:

{AppName}_get_state - Get current state
{AppName}_set_state - Set state (running/paused/stopped)

Agent-Controlled Tools

If the app has @agent_controlled decorated methods, one tool per operation:

Name: {AppName}_{operation_name}
Example: SmartApp_optimize_gain
Schema: From the schema parameter of the @agent_controlled decorator

These tools execute inside the process loop with access to live measurements. The app must be in running state for these tools to work.

Request:

{
  "name": "SmartApp_optimize_gain",
  "arguments": {
    "node_id": 8,
    "strategy": "max_snr"
  }
}

Response:

{
  "success": true,
  "result": {
    "result": {
      "status": "applied",
      "previous_gain": 15.0,
      "new_gain": 17.0
    },
    "request_id": "abc-123-def"
  }
}

Error (app not running):

{
  "success": true,
  "result": {
    "error": "App 'SmartApp' is not running (state: stopped). Start the app first."
  }
}

Error (timeout):

{
  "success": true,
  "result": {
    "error": "Timeout waiting for operation 'optimize_gain' (request_id=abc-123, timeout=11s)."
  }
}

Tool Registry API

class ai_nn_controller.mcp.tool_registry.MCPToolRegistry

Central registry for MCP tools.

classmethod register_tool(tool): Register an MCP tool.

classmethod list_tools()

Tool Schema Lookup

class ai_nn_controller.mcp.tool_registry.MCPTool

Represents a single MCP tool.

Parameters:

name – Tool name
description – Human-readable description
input_schema – JSON Schema for input validation
handler – Async function to execute the tool
app_name – Associated application name
tool_type – “control”, “measurement”, “state”, or “agent_controlled”

to_mcp_format(): Convert to MCP protocol format.

Claude Desktop Integration

To integrate with Claude Desktop, add to your MCP configuration file:

{
  "mcpServers": {
    "ai_nn_controller": {
      "command": "curl",
      "args": ["-X", "POST", "http://localhost:8000/mcp/message"]
    }
  }
}

Or use the HTTP transport directly in Claude’s settings.

Example Usage with AI Agents

An AI agent can:

Discover tools: Query /mcp/tools to see available capabilities
Read state: Call {App}_get_state to check if app is running
Start app: Call {App}_set_state with {"state": "running"}
Read measurements: Call {App}_get_measurements
Send commands: Call {App}_set_gain or other control tools
Run in-loop operations: Call {App}_optimize_gain or other agent-controlled tools

Example conversation:

User: "Check the gain on node 3"
Agent: [Calls NetworkApp1_get_measurements with node_id=3]
Agent: "The current gain on node 3 is 20.5 dB"

User: "Set it to 15 dB"
Agent: [Calls NetworkApp1_set_gain with node_id=3, target_gain=15]
Agent: "Done. I've set the target gain to 15 dB"

MCP Server Implementation

class ai_nn_controller.mcp.server.MCPServer

MCP Server that exposes AIC tools to AI agents.

async handle_request(request): Handle an MCP protocol request.

class ai_nn_controller.mcp.server.StdioMCPServer

MCP Server with stdio transport for Claude Desktop.

async run(): Run the server, reading from stdin and writing to stdout.