MCP Servers

Professional

Connect external tool servers via the Model Context Protocol to extend AI agent capabilities with specialized tools.

Overview

MCP (Model Context Protocol) Servers are external tool servers that extend the capabilities of NetStacks AI features. By connecting an MCP server, you give NOC agents and AI Chat access to specialized tools that can query monitoring systems, look up assets in a CMDB, check circuit status, or perform any other operation exposed through the MCP protocol.

NetStacks supports three transport types for connecting to MCP servers:

stdio — Launches a local process and communicates over standard input/output. Best for MCP servers packaged as CLI tools or npm packages that run on the same host as the Controller.
SSE (Server-Sent Events) — Connects to a remote MCP server over an HTTP-based event stream. Ideal for long-running remote servers that push updates to the Controller.
HTTP — Connects to a remote MCP server via standard REST API calls. Suitable for stateless MCP servers exposed behind load balancers or API gateways.

Why MCP?

The Model Context Protocol is an open standard for connecting AI systems to external tools and data sources. Instead of building custom integrations for every monitoring platform, CMDB, or ticketing system, you can connect a single MCP server that exposes those capabilities as discoverable tools.

How It Works

The MCP integration follows a lifecycle of registration, discovery, enablement, and invocation:

Server Registration

An administrator registers an MCP server by providing a name, transport type, connection details (command and arguments for stdio, URL and authentication for SSE/HTTP), and a server type classification. Each server is scoped to an organization and can be enabled or disabled independently.

Tool Discovery

When the Controller connects to an MCP server, it automatically enumerates all available tools. Each discovered tool includes a name, description, and an input schema that defines what parameters the tool accepts. Tools are upserted on each connection so the registry stays current if the server adds or removes capabilities.

Per-Tool Enablement

Administrators can enable or disable individual tools from any MCP server. This gives fine-grained control over which capabilities are available to AI agents. For example, you might enable read-only Grafana queries but disable a tool that can create incidents in your ticketing system until you have tested it thoroughly.

Health Monitoring

The Controller periodically checks the health of each enabled MCP server. If a server becomes unreachable, it is marked unhealthy and its tools are temporarily removed from the active tool registry. When connectivity is restored, the server is automatically reconnected and its tools are re-discovered.

Tool Invocation

During an AI agent's ReAct loop or an AI Chat session, the LLM can select and invoke any enabled MCP tool. The Controller routes the invocation to the appropriate MCP server, passes the parameters, and returns the result to the AI for further reasoning.

Connecting an MCP Server

Follow these steps to connect an MCP server and make its tools available to AI features.

Step 1: Navigate to MCP Servers

Go to AI → MCP Servers in the Controller web interface. You will see a list of currently registered servers with their health status.

Step 2: Add a New Server

Click Add Server and enter a descriptive name for the server (e.g., "Grafana Monitoring Tools" or "ServiceNow CMDB").

Step 3: Select Transport Type

Choose the transport type that matches how your MCP server is deployed:

stdio — For local processes (provide command and arguments)
SSE — For remote servers using Server-Sent Events (provide URL)
HTTP — For remote REST-based servers (provide URL)

Step 4: Configure Connection Details

For stdio, provide the command to launch the server and any arguments. For SSE or HTTP, provide the server URL and any authentication headers (Bearer token, API key).

Step 5: Test the Connection

Click Test Connection to verify the Controller can reach the MCP server and perform an initial tool discovery.

Step 6: Review Discovered Tools

After a successful connection test, the Controller displays all tools discovered from the server. Review each tool's name, description, and input schema.

Step 7: Enable or Disable Specific Tools

Toggle individual tools on or off based on your requirements. Only enabled tools are available to AI agents and AI Chat.

Review tools before enabling

Some MCP servers expose tools that can modify external systems (create tickets, restart services, push configurations). Review each tool's description and input schema carefully before enabling it.

Step 8: Monitor Server Health

The MCP Servers list shows a health indicator for each server. Green means the server is connected and responding. Red indicates a connectivity issue. Click on a server to view detailed health history and recent tool invocations.

Code Examples

stdio Transport Configuration

Launch a local MCP server as a child process. This is common for npm-packaged MCP servers:

stdio-server-config.jsonjson

{
  "name": "Network Monitoring Tools",
  "transport_type": "stdio",
  "command": "npx",
  "args": ["-y", "@netstacks/mcp-monitoring"],
  "auth_type": "none",
  "server_type": "monitoring",
  "enabled": true
}

SSE Transport Configuration

Connect to a remote MCP server that streams responses via Server-Sent Events:

sse-server-config.jsonjson

{
  "name": "Grafana MCP Server",
  "transport_type": "sse",
  "url": "https://mcp.internal.example.net/events",
  "auth_type": "bearer",
  "headers": {
    "Authorization": "Bearer eyJhbGciOiJIUzI1NiIs..."
  },
  "server_type": "monitoring",
  "enabled": true
}

HTTP Transport Configuration

Connect to a stateless MCP server exposed as a REST API:

http-server-config.jsonjson

{
  "name": "ServiceNow CMDB",
  "transport_type": "http",
  "url": "https://mcp.internal.example.net/api",
  "auth_type": "api_key",
  "headers": {
    "X-API-Key": "snmc-a1b2c3d4e5f6..."
  },
  "server_type": "cmdb",
  "enabled": true
}

Tool Discovery Response

When the Controller connects to an MCP server, it receives a list of available tools with their schemas:

tool-discovery-response.jsonjson

{
  "tools": [
    {
      "name": "query_grafana",
      "description": "Execute a PromQL query against Grafana and return time-series data",
      "input_schema": {
        "type": "object",
        "properties": {
          "query": { "type": "string", "description": "PromQL expression" },
          "range": { "type": "string", "description": "Time range (e.g., 1h, 6h, 24h)" },
          "step": { "type": "string", "description": "Query resolution step (e.g., 15s, 1m)" }
        },
        "required": ["query"]
      }
    },
    {
      "name": "lookup_device_cmdb",
      "description": "Look up a network device in the CMDB by hostname or IP address",
      "input_schema": {
        "type": "object",
        "properties": {
          "hostname": { "type": "string", "description": "Device hostname" },
          "ip_address": { "type": "string", "description": "Device management IP" }
        }
      }
    },
    {
      "name": "check_circuit_status",
      "description": "Check the operational status of a WAN circuit by circuit ID",
      "input_schema": {
        "type": "object",
        "properties": {
          "circuit_id": { "type": "string", "description": "Circuit identifier (e.g., CKTID-12345)" }
        },
        "required": ["circuit_id"]
      }
    }
  ]
}

Per-Tool Enable/Disable

After discovery, administrators can enable or disable individual tools:

manage-tools.shbash

# Enable a specific tool by ID
curl -X PATCH https://controller.example.net/api/mcp/tools/a1b2c3d4/enabled \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'

# Disable a tool (removes it from the active tool registry)
curl -X PATCH https://controller.example.net/api/mcp/tools/e5f6g7h8/enabled \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'

# List all enabled tools for the organization
curl https://controller.example.net/api/mcp/tools?enabled=true \
  -H "Authorization: Bearer <token>"

Questions & Answers

Q: What is MCP (Model Context Protocol)?: A: MCP is an open standard for connecting AI systems to external tools and data sources. It defines how an AI host (like NetStacks) discovers, invokes, and receives results from tool servers. This allows NetStacks to integrate with any MCP-compatible server without building custom connectors for each external system.
Q: What transport types does NetStacks support for MCP?: A: NetStacks supports three transport types: stdio for local processes launched as child processes on the Controller host, SSE (Server-Sent Events) for remote servers that stream responses over HTTP, and HTTP for stateless remote servers that respond to standard REST API calls. Choose stdio for local tools, SSE for persistent connections, and HTTP for load-balanced or serverless deployments.
Q: How do I discover what tools an MCP server provides?: A: Tool discovery is automatic. When you connect an MCP server, the Controller queries the server for its list of available tools. Each tool comes with a name, description, and input schema. The discovered tools appear in the server's detail view in the Controller UI. If the server adds new tools later, they are discovered on the next health check or reconnection.
Q: Can I disable specific tools from an MCP server?: A: Yes. After tool discovery, each tool can be individually enabled or disabled. Disabled tools are not available to NOC agents or AI Chat. This is useful when a server exposes both read-only and write tools and you want to restrict AI access to read-only operations until you have validated the write tools.
Q: How does MCP server health monitoring work?: A: The Controller periodically checks each enabled MCP server's connectivity. For stdio servers, it verifies the child process is still running. For SSE and HTTP servers, it sends a health check request to the configured URL. If a server fails health checks, it is marked unhealthy and its tools are temporarily removed from the active registry. The server is automatically reconnected when it becomes reachable again.
Q: Can NOC agents use MCP server tools?: A: Yes. Enabled MCP tools are added to the tool registry that NOC agents access during their ReAct reasoning loops. For example, a triage agent investigating a high-latency alert could use a Grafana MCP tool to pull interface utilization metrics, a CMDB tool to look up the affected device's circuit provider, and a circuit status tool to check for provider-side outages — all without any custom integration code.
Q: Do MCP servers have access to my network devices?: A: MCP servers do not connect to your network devices directly. They provide tools that the Controller invokes on behalf of AI agents. The MCP server only has access to whatever external systems it is configured to reach (e.g., a Grafana instance, a CMDB API). It does not receive NetStacks credentials or direct device access.

Troubleshooting

Server connection failing

If the Controller cannot connect to an MCP server:

stdio — Verify the command exists on the Controller host and is executable. Check that any required npm packages are installed. Review the Controller logs for process spawn errors.
SSE / HTTP — Verify the URL is reachable from the Controller host. Check firewall rules, DNS resolution, and TLS certificate validity. Confirm the authentication token or API key is correct and not expired.

Tools not discovered

If the server connects but no tools appear, the MCP server may not be implementing the tool listing endpoint correctly. Verify that the server responds to the MCP tools/list request. Check the server's own logs for errors during tool enumeration.

Tool execution failing

If a tool is invoked but returns an error:

Check the tool's input schema and verify the AI is sending correctly formatted parameters
Verify the MCP server has the necessary permissions to access the external system (e.g., Grafana API key with read access, CMDB service account)
Review the MCP server's logs for detailed error messages

Health check failing intermittently

Intermittent health check failures may indicate the MCP server process is crashing and restarting. For stdio servers, check the process manager or container runtime logs. For remote servers, check for network timeouts or rate limiting on the health check endpoint.

Tip

Enable debug logging on the Controller (RUST_LOG=debug) to see detailed MCP protocol messages, including tool discovery requests and responses.

Learn more about how MCP servers integrate with other NetStacks features:

NOC Agents — Autonomous agents that use MCP tools during ReAct reasoning loops
LLM Configuration — Configure which LLM provider powers tool selection and invocation
AI Chat — Interactive chat sessions that can invoke MCP tools for real-time answers
System Settings — Global configuration for AI features and MCP server defaults
Quick Actions — One-click API call templates that complement MCP tool capabilities