Implementing the NAIM Framework over the Model Context Protocol

fengchongllly@gmail.com

OPS NMOP NAIM MCP YANG AI network management NAIM (Natural AI Interface Modeling) is a semantic intermediate representation framework for AI-assisted network management. It consists of two specifications: a core specification that defines the NAIM Document format, YANG-aware node templates, type representation, and design-time Skills A-D; and an operations specification that defines the Operation IR, runtime execution semantics, transaction and compensation model, and runtime Skills E-F. The Model Context Protocol (MCP) has emerged as the dominant standard for AI hosts to discover and invoke external capabilities. However, MCP delegates semantic understanding entirely to the AI model through natural language Tool descriptions, which is insufficient for the structured precondition checking, constraint validation, and compensation logic that reliable network management requires. This document specifies how the NAIM framework is implemented over MCP. It defines the Originator/Handler architectural split, the MCP Resources through which NAIM LLM Context Views are distributed, the minimal MCP Tool surface through which Operation IRs are submitted, and the complete interaction flow from natural language intent to validated network execution. This document is self-contained with respect to the MCP integration architecture; it references and for the NAIM Document format, Operation IR structure, and execution engine semantics, which are not redefined here.

Introduction

The Semantic Gap in MCP-Based Network Management YANG provides precise structural modeling for network management, used with NETCONF and RESTCONF . 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 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.

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: 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.

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.

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 ();
The NAIM Handler's role as an MCP Server ();
MCP Resources for NAIM LLM Context View distribution ();
MCP Tools for Operation IR submission ();
MCP Prompts for NAIM Skill invocation ();
The complete MCP interaction flow ();
Information segregation principles ();
Open issues in MCP protocol design ();
MCP-specific security considerations ().

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

Requirements Language The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here.

Terminology

YANG:: The data modeling language .
NETCONF:: Network Configuration Protocol .
RESTCONF:: REST-based network configuration protocol .
MCP:: Model Context Protocol . A protocol defining how AI hosts discover and invoke external tools, resources, and prompts.
NAIM Document:: A structured artifact conforming to the canonical JSON schema defined in . A NAIM Document represents the semantics of one YANG module or one YANG submodule, including node types, type systems, operational preconditions, side effects, visibility conditions, and constraints.
Canonical JSON:: The normative primary format of a NAIM Document. All deterministic operations operate on Canonical JSON as the authoritative internal object.
Operation IR:: Operation Intermediate Representation. A structured JSON object defined in that describes a single runtime operation intent, including target YANG path, operation type, values, datastore selection, precondition state, and compensation.
Originator:: An AI system (typically a large language model) that consumes LLM Context Views and produces Operation IRs in response to natural language user intent. The Originator is the intent encoder; it is NOT the executor.
Handler:: A deterministic software component that consumes NAIM Canonical JSON to validate Operation IRs and execute them against target network devices via NETCONF or RESTCONF. The Handler is the semantic authority; it does NOT interpret natural language.
LLM Context View:: A derived, machine-optimized but human-readable Markdown view of a NAIM Document, intended for consumption by Originators as prompt context. Retains path, node-type, type, constraints, writable status, visibility conditions, and concise description, omitting structural boilerplate and execution details to reduce token consumption. Generation rules are defined in .

The Originator/Handler Architecture

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: 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 , 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.

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.

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.

Data Flow Specification The following table specifies the format for each data flow:

Data Flow	Format	Rationale
NAIM Doc -> Originator	LLM Context View (Markdown)	Semantic density; token efficiency
NAIM Doc -> Handler	Canonical JSON (internal)	Machine-parseable; schema-validatable
Originator -> Handler	Operation IR (JSON)	Machine-parseable interface contract
Handler -> Device	NETCONF XML / RESTCONF	Target protocol requirement
Handler -> Originator	Natural language summary	Human-readable result
Handler -> Audit	Execution Report (JSON)	Machine-parseable; auditable

NAIM Handler as MCP Server

Overview When exposed as an MCP Server, a NAIM Handler implements the Originator/Handler architecture defined in : 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.

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.

MCP Resources: NAIM Context Distribution

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 . It retains path, node-type, type, constraints, writable status, visibility conditions, and concise description, omitting structural boilerplate to reduce token consumption. Resource URIs: Returns: NAIM LLM Context View (text/markdown) -> Content: Semantic description of the resource, fields, constraints, preconditions, side effects, and operation vocabulary ]]> Example: 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 ]]>

Operation IR Schema Resource The Handler SHOULD expose the Operation IR JSON Schema as an MCP Resource, enabling Originators to self-validate before submission: Returns: JSON Schema for NAIM Operation IR (application/json) -> Content: The schema that Originators must conform to when generating Operation IRs ]]>

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.

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.

MCP Tools: Minimal Execution Surface The NAIM Handler exposes a minimal set of MCP Tools. Consistent with the trust boundary defined in , the RECOMMENDED surface consists of a single execution entry point and supporting validation/dry-run tools.

execute_operation_ir The primary execution entry point. Accepts a complete NAIM Operation IR (as defined in ) and executes it against the target network device. Upon receiving an Operation IR, the Handler performs the validation and execution pipeline defined in Skill F:

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

validate_operation_ir Validation without execution, supporting Originator self-correction. When validation fails, the Handler SHOULD return a Structured Error Report as defined in , 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.

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). This tool corresponds to the dry-run execution mode defined in Section 11.

MCP Prompts (OPTIONAL) NAIM Skills MAY be exposed as MCP Prompts, enabling MCP hosts with Prompt selection UI to surface NAIM workflows.

Network Intent Execution Prompt

NAIM Document Modeling Prompt

The Complete MCP Interaction Flow This section illustrates the end-to-end interaction between an MCP Host, a NAIM MCP Server, and a target network device.

Normal Flow 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 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." ]]>

Validation Failure with Self-Correction 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 ]]>

Compensation Flow { "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": "..." } } } ]]>

Information Segregation A NAIM MCP Server deliberately withholds certain information from Originator-accessible MCP surfaces. This segregation keeps the AI model in the role of intent encoder and removes it from the role of execution decision-maker. The following MUST NOT be exposed through MCP Resources or Tool responses:

NAIM Canonical JSON: The Handler's authoritative representation. The Originator receives only the LLM Context View.
Device credentials: Managed by the Handler through environment variables or secret management, never exposed through MCP.
NETCONF XML / RESTCONF request construction: Protocol-specific message generation is a Handler concern. The Originator sees only Operation IRs and natural language results.
Compensation execution internals: Triggered automatically by the Handler on failure. The Originator declares compensation intent in the Operation IR; the Handler executes it.
YANG module internals: Import statements, prefix mappings, YANG version selection, and namespace declarations are Handler concerns.

Discouraged Pattern: Per-Operation Tool Wrapping An alternative approach -- wrapping each NAIM operation as an independent MCP Tool -- is explicitly discouraged: This pattern degrades NAIM to the semantic level of a conventional MCP Tool server. Precondition checking, field constraint validation, and compensation become the Originator's responsibility -- a responsibility it cannot reliably fulfill given only natural language descriptions. The single-entrypoint pattern (execute_operation_ir) preserves the Handler as the semantic authority. All semantic validation, constraint enforcement, precondition checking, and compensation logic remain in the deterministic Handler, not in the probabilistic AI model.

Implementation Guidance

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 . 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 . 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.

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.

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 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.

Open Issues: MCP Protocol Considerations This section identifies open questions in the current MCP protocol design that the community may wish to address. These observations arise from practical experience implementing NAIM over MCP and are offered for community discussion, not as normative requirements.

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 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.

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 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.

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.

Security Considerations

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.

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.

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.

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.

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.

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 (SSH) or RESTCONF (TLS).

IANA Considerations This document requests no IANA actions at this time. If the naim:// URI scheme is adopted for MCP Resource identification, a future document may request registration with IANA per .

References Normative References &RFC2119; &RFC6241; &RFC7950; &RFC8040; &RFC8174; NAIM: A Canonical Data Format for AI-Assisted YANG Modeling Operation Intent Intermediate Representation for Model-Driven Network Execution Informative References &RFC7595; &RFC8343; Model Context Protocol Specification Anthropic https://modelcontextprotocol.io/specification

MCP Server Manifest Example The following illustrates how a NAIM Handler describes itself to an MCP host:

LLM Context View Example The following illustrates the LLM Context View that would be returned by the MCP Resource naim://router-1/interfaces/interface, derived from a NAIM Canonical JSON document modeling the ietf-interfaces module :

Operation IR Submission Example The following shows a complete Operation IR as submitted through the execute_operation_ir MCP Tool, corresponding to the user intent "Set the MTU of interface eth0 to 9000 on router-1": The Handler processes this Operation IR as follows:

Locates /ietf-interfaces:interfaces/interface in the Canonical JSON; confirms it is a list keyed by name.
Validates mtu: 9000 against the type constraint (uint16, range 68..65535); validation passes.
Verifies writable: true for the mtu leaf.
Issues a RESTCONF GET to verify the interface exists and enabled == true.
Compiles and sends the NETCONF <edit-config>:

eth0 9000 ]]>

On success, returns:

On failure, automatically executes the compensation operation (restore MTU to 1500) and reports the outcome.