Implementing the NAIM Framework over the Model Context Protocol

1.1. The Semantic Gap in MCP-Based Network Management

YANG [RFC7950] provides precise structural modeling for network management, used with NETCONF [RFC6241] and RESTCONF [RFC8040]. However, YANG does not express operational preconditions, side effects, compensation logic, or natural language intent alignment. When AI agents attempt to drive NETCONF operations from natural language, these gaps produce systematic failures.¶

The Model Context Protocol [MCP] provides ecosystem-wide tool discovery and invocation, but its design delegates semantic understanding entirely to the AI model. MCP Tool descriptions are natural language strings; the AI system is expected to determine when and how to call a tool based on its general understanding, without machine-processable semantic constraints.¶

This design is sufficient for simple, stateless operations but insufficient for network management, which requires:¶

• precondition verification before configuration changes;¶
• constraint validation against YANG type systems;¶
• compensation (undo) logic for failed multi-step operations;¶
• datastore selection and transaction coordination; and¶
• field-level semantic understanding that natural language descriptions cannot reliably convey.¶

The gap is representational, not model-quality-dependent. Even a highly capable language model cannot reliably infer from a natural language MCP Tool description whether a configuration change requires a specific prior device state, whether repeated execution is safe, or how to reverse a failed change. The information is simply not present.¶

1.2. NAIM as the Semantic Bridge

NAIM (Natural AI Interface Modeling) bridges this gap by providing a semantic intermediate representation between natural language intent and YANG/NETCONF/RESTCONF execution. NAIM is defined across two specifications:¶

[NAIM-CORE] defines the design-time framework:¶

• The NAIM Document (Canonical JSON) -- a semantic intermediate representation capturing network resource models with full semantic annotation: node types (leaf, leaf-list, container, list, choice/case, rpc/action, notification), type systems mapping to YANG base types, operational preconditions, side effects, visibility conditions (if-feature/when), and constraints;¶
• Dual-format representation: Canonical JSON (authoritative) and Markdown View (human-reviewable), with round-trip fidelity;¶
• The YANG path convention (module-name-prefixed absolute schema paths);¶
• Skills A-D: Conversational Modeling, Summarization, YANG Generation, and Reverse Engineering;¶
• The Validation-Reflection-Retry mechanism for AI output quality control.¶

[NAIM-OP] defines the runtime framework:¶

• The NAIM Operation IR -- a structured JSON intent object (operation, target YANG path with key predicates, values, datastore selection, precondition_state, compensation);¶
• Context completeness classes (full, partial, skeleton);¶
• Skills E (conversational intent modeling) and F (protocol execution: Operation IR validation, precondition verification via device read, NETCONF XML / RESTCONF request compilation, execution, and compensation);¶
• Datastore selection rules, soft constraints, transaction and compensation model;¶
• Dry-run execution preview semantics.¶

1.3. Scope of This Document

This document specifies how the NAIM framework is implemented over MCP. It covers:¶

• The Originator/Handler architectural decomposition and trust boundary (Section 4);¶
• The NAIM Handler's role as an MCP Server (Section 5);¶
• MCP Resources for NAIM LLM Context View distribution (Section 6);¶
• MCP Tools for Operation IR submission (Section 7);¶
• MCP Prompts for NAIM Skill invocation (Section 8);¶
• The complete MCP interaction flow (Section 9);¶
• Information segregation principles (Section 10);¶
• Open issues in MCP protocol design (Section 13);¶
• MCP-specific security considerations (Section 14).¶

This document does NOT define the NAIM Document format, node templates, YANG generation rules, Operation IR structure, or execution engine -- these are defined in [NAIM-CORE] and [NAIM-OP].¶

4.1. Architectural Rationale

The Originator/Handler split is the foundational architectural decomposition for implementing NAIM over MCP. It separates AI-driven intent encoding from deterministic execution:¶

User natural language intent
        |
        v
   Originator (AI)
        | consumes LLM Context View
        |   (via MCP Resources)
        | produces Operation IR
        v
   Handler (deterministic, MCP Server)
        | consumes Canonical JSON (internal)
        | validates Operation IR
        | executes via NETCONF/RESTCONF
        | compensates on failure
        v
   Target Network Device

The Originator is an AI system that consumes LLM Context Views retrieved through MCP Resources and produces Operation IRs. The Originator's role is intent encoding: translating natural language into a structured, validatable operation description.¶

The Handler is a deterministic software component that consumes the NAIM Canonical JSON document and executes Operation IRs against target network devices. Per [NAIM-OP], the Handler performs path-based node lookup, value validation against type and constraint definitions, writable-state verification, precondition verification via device read, NETCONF XML / RESTCONF request compilation, execution, and automatic compensation on failure.¶

4.2. Trust Boundary

The split enforces a critical trust boundary:¶

• The AI (Originator) is not trusted for execution decisions. It encodes intent; it does not validate or execute.¶
• The Handler is the semantic authority. It validates all Operation IRs against the NAIM Canonical JSON before execution, regardless of the claimed source.¶
• An Operation IR is an untrusted input that the Handler validates, not a trusted command that the Handler executes.¶

This trust model is the opposite of conventional MCP Tool usage, where the AI model is fully trusted to determine which tools to call, in what order, and with what parameters. NAIM constrains the AI to intent encoding and preserves deterministic control over execution.¶

4.3. Design Tension with MCP and Its Resolution

A critical design tension exists between MCP's trust model and NAIM's trust model:¶

• MCP trusts the AI model to determine which tools to call, in what order, with what parameters. The AI is the decision-maker.¶
• NAIM does not trust the AI model for execution decisions. The Originator is the intent encoder; the Handler is the executor.¶

This tension is resolved by constraining the MCP Tool surface: the Handler exposes few, coarse-grained Tools (ideally a single execution entry point) rather than many fine-grained Tools that the AI could combine arbitrarily. Semantic control remains inside the Handler.¶

4.4. Data Flow Specification

The following table specifies the format for each data flow:¶

5.1. Overview

When exposed as an MCP Server, a NAIM Handler implements the Originator/Handler architecture defined in Section 4: it exposes LLM Context Views as MCP Resources and accepts Operation IRs through a minimal MCP Tool surface. The Handler retains all semantic authority; the MCP integration is a transport and discovery layer.¶

A NAIM MCP Server MUST:¶

• expose at least one MCP Resource returning a NAIM LLM Context View;¶
• expose the execute_operation_ir MCP Tool; and¶
• validate all received Operation IRs against its internal NAIM Canonical JSON before execution.¶

A NAIM MCP Server SHOULD:¶

• expose a validate_operation_ir MCP Tool for pre-execution validation; and¶
• expose the Operation IR JSON Schema as an MCP Resource.¶

A NAIM MCP Server MAY:¶

• expose a dry_run_operation_ir MCP Tool;¶
• expose MCP Prompts for NAIM Skill invocation; and¶
• expose multiple resource-specific LLM Context Views.¶

5.2. Implementation Maturity Prerequisite

MCP integration is RECOMMENDED only after the NAIM core is fully implemented and validated -- Operation IR validation working end-to-end, and at least one complete resource cycle (create/update/delete with compensation) validated against a real network device.¶

6.1. LLM Context View Resources

The NAIM Handler exposes NAIM LLM Context Views as MCP Resources, enabling Originators to retrieve semantic context before generating Operation IRs.¶

The LLM Context View is a derived Markdown format defined in [NAIM-CORE]. It retains path, node-type, type, constraints, writable status, visibility conditions, and concise description, omitting structural boilerplate to reduce token consumption.¶

Resource URIs:¶

naim://{device-id}/{resource-path}
  -> Returns: NAIM LLM Context View (text/markdown)
  -> Content: Semantic description of the resource,
              fields, constraints, preconditions,
              side effects, and operation vocabulary

Example:¶

naim://router-1/interfaces/interface
  -> Returns LLM Context View containing:
    - Node: list
      /ietf-interfaces:interfaces/interface
      (key: name)
    - Leaves: name (string, config false),
      enabled (boolean, writable),
      oper-status (enumeration, read-only)
    - Operations: create, update, delete with
      preconditions and side effects
    - Operation IR Schema URI

6.2. Operation IR Schema Resource

The Handler SHOULD expose the Operation IR JSON Schema as an MCP Resource, enabling Originators to self-validate before submission:¶

naim://{device-id}/schema/operation-ir
  -> Returns: JSON Schema for NAIM Operation IR
              (application/json)
  -> Content: The schema that Originators must
              conform to when generating Operation IRs

6.3. Resource Scope and Granularity

A NAIM MCP Server MAY expose LLM Context Views at multiple levels of granularity:¶

• Module-level: A single resource covering all nodes in a YANG module. Suitable for small modules but may exceed token budgets for large ones.¶
• Subtree-level: Resources scoped to specific containers or lists. The RECOMMENDED granularity for production use.¶
• Node-level: Individual node resources. Fine-grained but may require multiple retrievals for a single operation.¶

The Handler SHOULD document its resource granularity in the MCP Server manifest.¶

6.4. Content Requirements

The LLM Context View returned by MCP Resources is the ONLY format the Originator needs. The NAIM Canonical JSON is an internal Handler artifact and MUST NOT be exposed through MCP Resources.¶

An LLM Context View MUST include:¶

• resource/node name and type;¶
• all field names with semantic types, required/optional status, constraints, and illustrative examples where present;¶
• supported operation names;¶
• for each operation: preconditions, side effects, and the parameter vocabulary;¶
• the Operation IR schema reference (URI); and¶
• any visibility conditions that affect field or operation availability.¶

An LLM Context View MUST omit:¶

• NETCONF XML / RESTCONF request construction details;¶
• response parsing details;¶
• internal metadata (version, organization, ownership); and¶
• raw JSON Schema syntax of the Canonical JSON.¶

7.1. execute_operation_ir

The primary execution entry point. Accepts a complete NAIM Operation IR (as defined in [NAIM-OP]) and executes it against the target network device.¶

{
  "name": "execute_operation_ir",
  "description": "Execute a validated network
    management operation. Before calling,
    retrieve the relevant resource context from
    naim:// resources to understand field
    constraints, preconditions, and the correct
    Operation IR structure. The Handler validates
    the IR against the NAIM Canonical JSON,
    checks preconditions against the live device,
    executes via NETCONF/RESTCONF, and triggers
    compensation automatically on failure.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "operation_ir": {
        "type": "object",
        "description": "A complete NAIM
          Operation IR object conforming to
          the schema at naim://{device-id}/
          schema/operation-ir."
      }
    },
    "required": ["operation_ir"]
  }
}

Upon receiving an Operation IR, the Handler performs the validation and execution pipeline defined in [NAIM-OP] Skill F:¶

1. Locate the target node in the NAIM Canonical JSON by path;¶
2. Validate all values fields against type, range, pattern, and constraints;¶
3. Verify writable: true for write operations;¶
4. If precondition_state is specified, issue a read to the device and verify current state matches declared preconditions;¶
5. If validation passes, compile to NETCONF XML or RESTCONF request and execute;¶
6. If the primary operation fails and compensation is defined, execute compensation operations in order.¶

7.2. validate_operation_ir

Validation without execution, supporting Originator self-correction.¶

{
  "name": "validate_operation_ir",
  "description": "Validate a NAIM Operation IR
    without executing it. Returns constraint
    violations, missing fields, and precondition
    evaluation results.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "operation_ir": { "type": "object" },
      "check_preconditions": {
        "type": "boolean",
        "description": "If true, issue a read
          to verify current device state against
          declared preconditions.",
        "default": false
      }
    },
    "required": ["operation_ir"]
  }
}

When validation fails, the Handler SHOULD return a Structured Error Report as defined in [NAIM-CORE], containing error_type, field_path, message, and expected format. This enables the Originator to apply the Validation-Reflection-Retry mechanism to correct the Operation IR without user intervention.¶

7.3. dry_run_operation_ir (OPTIONAL)

Returns the exact NETCONF XML or RESTCONF request that would be sent without executing it. Supports human review before committing to high-risk operations (device reload, routing protocol changes, firewall rule modifications).¶

{
  "name": "dry_run_operation_ir",
  "description": "Preview the NETCONF XML or
    RESTCONF request that would be sent for an
    Operation IR, without executing it. Returns
    the rendered protocol messages for human
    review.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "operation_ir": { "type": "object" }
    },
    "required": ["operation_ir"]
  }
}

This tool corresponds to the dry-run execution mode defined in [NAIM-OP] Section 11.¶

8.1. Network Intent Execution Prompt

{
  "name": "execute_network_intent",
  "description": "Execute a natural language
    network management intent with full semantic
    validation and automatic compensation.",
  "arguments": [
    {
      "name": "intent",
      "description": "Natural language
        description of the desired operation",
      "required": true
    },
    {
      "name": "device",
      "description": "Target device identifier",
      "required": false
    },
    {
      "name": "resource",
      "description": "The resource path to
        operate on (e.g., /ietf-interfaces:
        interfaces/interface)",
      "required": false
    }
  ]
}

8.2. NAIM Document Modeling Prompt

{
  "name": "model_network_resource",
  "description": "Interactively model a network
    resource through structured dialogue,
    producing a NAIM Document. Corresponds to
    NAIM Skill A (Conversational Modeling).",
  "arguments": [
    {
      "name": "resource_description",
      "description": "Natural language
        description of the network resource
        to model",
      "required": true
    }
  ]
}

9.1. Normal Flow

Step 1: Context Retrieval
  MCP Host -> resources/read(
    uri="naim://router-1/interfaces/interface")
  NAIM MCP Server ->
    NAIM LLM Context View (text/markdown)
  [Originator now has: field names, types,
   constraints, preconditions for
   create/update/delete, side effects,
   Operation IR vocabulary]

Step 2: Intent Processing
  User: "Disable interface eth0 on router-1"
  Originator (LLM): generates NAIM Operation IR:
  {
    "operation": "update",
    "target": "/ietf-interfaces:interfaces/
      interface[name='eth0']",
    "values": { "enabled": false },
    "context": {
      "datastore": "running",
      "transaction_id": "tx-2026-07-16-001"
    },
    "precondition_state": {
      "/ietf-interfaces:interfaces/
        interface[name='eth0']/oper-status":
          "up"
    },
    "compensation": [
      {
        "operation": "update",
        "target": "/ietf-interfaces:interfaces/
          interface[name='eth0']",
        "values": { "enabled": true },
        "context": { "datastore": "running" }
      }
    ]
  }

Step 3: Validation (OPTIONAL)
  MCP Host -> tools/call(
    name="validate_operation_ir",
    arguments={
      "operation_ir": {...},
      "check_preconditions": true
    })
  NAIM MCP Server -> {
    "valid": true,
    "preconditions": "satisfied",
    "warnings": []
  }

Step 4: Execution
  MCP Host -> tools/call(
    name="execute_operation_ir",
    arguments={ "operation_ir": {...} })
  NAIM Handler:
    - Validates Operation IR against
      NAIM Canonical JSON
    - Issues precondition read to device
    - Confirms oper-status == "up"
    - Compiles NETCONF <edit-config>
      with enabled=false
    - Executes against router-1
    - Returns execution report
  NAIM MCP Server -> {
    "status": "success",
    "summary": "Interface eth0 disabled
      on router-1."
  }

Step 5: Result Communication
  Originator -> User: "Interface eth0 on
    router-1 has been disabled successfully."

9.2. Validation Failure with Self-Correction

Step 1: Context Retrieval (same as above)

Step 2: Originator generates Operation IR
  with invalid MTU value

Step 3: Validation
  MCP Host -> tools/call(
    name="validate_operation_ir",
    arguments={
      "operation_ir": {
        ... "values": { "mtu": 100000 } ...
      }
    })
  NAIM MCP Server -> {
    "valid": false,
    "errors": [
      {
        "error_type": "constraint_violation",
        "field_path": "/values/mtu",
        "message": "MTU value 100000 exceeds
          allowed range 68..65535.",
        "expected": "Integer in range 68..65535"
      }
    ]
  }

Step 4: Originator applies
  Validation-Reflection-Retry:
  Regenerates Operation IR with corrected
  value (mtu: 9000)

Step 5: Execution with corrected
  Operation IR succeeds

9.3. Compensation Flow

Step 1-2: Context retrieval and intent
  processing (same as above)

Step 3: Execution of step 1 in a multi-step
  transaction succeeds

Step 4: Execution of step 2 fails
  NAIM Handler:
    - Detects failure of step 2
    - Automatically executes compensation
      for step 1
    - Returns execution report with
      compensation outcome

Step 5: NAIM MCP Server -> {
    "status": "partial_failure",
    "summary": "Step 2 failed. Step 1 has
      been automatically rolled back via
      compensation.",
    "details": {
      "step_1": { "status": "compensated" },
      "step_2": {
        "status": "failed",
        "error": "..."
      }
    }
  }

12.1. Recommended Sequence

Implementors SHOULD follow this sequence:¶

Phase 1 -- NAIM Core Implementation

Implement the NAIM Document format, Canonical JSON validation, Skills A-D, and the NAIM tool layer per [NAIM-CORE]. Validate with a well-understood YANG module.¶

Phase 2 -- Operation IR Implementation

Implement the Operation IR format, validation pipeline, precondition checking, NETCONF/RESTCONF compilation, and compensation mechanism per [NAIM-OP]. Validate with complete resource lifecycles against real devices.¶

Phase 3 -- MCP Server Integration

Implement the MCP Server wrapper per this document: LLM Context View resources, execution and validation tools, and optionally Skill-invocation prompts. Validate the complete flow with an MCP-compatible host.¶

Phase 4 -- Production Hardening

Implement distributed locking for concurrent operation safety, the Validation-Reflection-Retry mechanism, Execution Report persistence, and access controls.¶

12.2. Multi-Device Deployment

Two deployment models are defined for multi-device environments:¶

Per-device Handler

Each network device is served by a dedicated NAIM MCP Server instance. Provides strict isolation but increases management overhead. RECOMMENDED for heterogeneous environments.¶

Multi-device Handler

A single NAIM MCP Server manages multiple devices, distinguishing them by device-id in the resource URI scheme. Reduces management overhead but requires the Handler to manage multiple Canonical JSON documents and device connections.¶

12.3. Hallucination Mitigation

AI-generated Operation IRs MUST be subject to structural validation before execution. The primary mitigation is the Handler's validation pipeline:¶

• All Operation IRs are validated against the NAIM Canonical JSON before execution; validation failures surface to the Originator for correction.¶
• The Validation-Reflection-Retry mechanism defined in [NAIM-CORE] provides automatic self-correction (RECOMMENDED maximum: 3 retries).¶
• If retries are exhausted, the system MUST surface the error to the user as a targeted natural language question.¶

13.1. Session Lifecycle

MCP does not define an explicit session lifecycle mechanism. There is no protocol-level session establishment, capability negotiation at session start, or graceful session termination. Transport-level connection state serves as an implicit session proxy, but this conflation means:¶

• if the server process restarts, all session state is lost silently;¶
• neither party has a protocol-level mechanism to detect that the other party considers the session ended; and¶
• capability changes during a session's lifetime have no notification path.¶

By contrast, NETCONF [RFC6241] defines an explicit session model with <hello> exchange, capability advertisement, session-id assignment, and <close-session> / <kill-session> operations. This provides clear lifecycle semantics that both endpoints can reason about.¶

This document takes no position on whether MCP should adopt a NETCONF-style explicit session model. However, implementors of NAIM MCP Servers SHOULD be aware that session state loss may occur without notification and SHOULD implement reconnection and state recovery logic at the application layer.¶

13.2. Stateful Servers and Cloud-Native Deployment

The current MCP server model maintains transport state in server process memory, which creates a one-to-one binding between client and server process. This design is incompatible with stateless deployment environments (serverless platforms, auto-scaling container orchestration) where request routing to a specific process instance cannot be guaranteed.¶

Community workarounds include externalizing transport state to external stores (e.g., Redis), but these are engineering patches applied outside the protocol specification rather than protocol-level solutions.¶

It is worth noting that the NAIM Operation IR [NAIM-OP] is designed as a self-contained object: each Operation IR carries its complete execution context (target, values, datastore, precondition_state, compensation) without depending on prior request history or server-side session state. This self-containment property means that a NAIM Handler's core validation and execution logic is inherently stateless -- the Handler does not need to maintain cross-request state to understand or execute an Operation IR. Where MCP session state management is required, it is confined to the MCP transport layer and does not affect the NAIM semantic processing layer.¶

13.3. Semantic Expressiveness of Tool Descriptions

MCP Tool descriptions are natural language strings with no machine-processable semantic structure. The AI model is expected to infer operational semantics -- preconditions, side effects, idempotency, compensation logic, field constraints -- from these descriptions alone.¶

For network management, this is a recognized gap: the semantics that determine safe execution (constraint validation, precondition verification, compensation chaining) cannot be reliably inferred from natural language. This gap is the primary motivation for the NAIM framework and the Originator/Handler architecture defined in this document.¶

The community may wish to consider whether MCP Tool descriptions should support optional structured semantic annotations alongside natural language descriptions, enabling Handlers that implement semantic validation to advertise their capabilities in machine-processable form.¶

14.1. Operation IR Trust

Operation IRs received through MCP Tools MUST NOT be trusted unconditionally. The Handler MUST perform full validation against the NAIM Canonical JSON before execution. The MCP Tool surface is a security boundary: any MCP-compatible client can invoke execute_operation_ir; the Handler's validation layer is the gate.¶

14.2. Network Device Access Control

NAIM Handlers manage credentials for network devices -- often the most sensitive systems in an IT infrastructure. Handlers MUST:¶

• support multi-factor authentication for device access where available;¶
• implement least-privilege access: write operations SHOULD use credentials scoped to the specific YANG subtrees involved;¶
• log all device authentication events, including failures; and¶
• support credential rotation without Handler restart.¶

14.3. Information Exposure

NAIM LLM Context Views, distributed through MCP Resources, contain detailed descriptions of device capabilities, field constraints, and operational semantics. This information may be sensitive. When distributed through MCP Resources, access MUST be subject to authorization checks equivalent to those applied to the underlying YANG models.¶

14.4. Configuration Change Safety

NAIM Handlers executing configuration changes MUST support:¶

• Dry-run mode: For devices supporting it, the Handler SHOULD use NETCONF confirmed-commit or equivalent mechanisms to enable automatic rollback;¶
• Change impact preview: Before executing a write operation, the Handler SHOULD surface the expected configuration delta to the user; and¶
• Rate limiting: Handlers SHOULD enforce rate limits on write operations to prevent accidental flooding.¶

14.5. Audit Trail

NAIM Handlers MUST maintain an audit trail of all execution events. For network management specifically, the audit trail SHOULD include:¶

• the complete Operation IR as received;¶
• the exact NETCONF XML or RESTCONF request transmitted;¶
• the device response (with sensitive data redacted);¶
• configuration deltas for write operations;¶
• precondition verification results; and¶
• compensation outcomes.¶

14.6. Transport Security

MCP communication between the Host and the NAIM MCP Server SHOULD be protected by transport-level security mechanisms. When the MCP Server communicates with network devices, it MUST use the secure transport mechanisms defined by NETCONF [RFC6241] (SSH) or RESTCONF [RFC8040] (TLS).¶