MCP Server

NeutronEDI exposes a hosted MCP server for agent harnesses that support MCP Streamable HTTP transport. The server provides callable X12 tools; companion skills provide the procedural knowledge for when and how agents should use those tools.

Server URL

Production MCP server URL:

https://api.neutronedi.com/mcp

Local development MCP server URL:

http://localhost:5100/mcp

The MCP server is outside the /api/v1 REST API namespace. It uses MCP protocol messages over Streamable HTTP, not REST request/response shapes.

Authentication

MCP requests use the same API key model as the REST API. Configure the agent harness to send the customer's API key on every MCP HTTP request:

X-API-Key: nedi_...

Do not put API keys in query strings. Missing or invalid keys receive an unauthorized response.

Generic harness shape:

{
  "mcpServers": {
    "neutron-edi": {
      "url": "https://api.neutronedi.com/mcp",
      "headers": {
        "X-API-Key": "${NEUTRON_EDI_API_KEY}"
      }
    }
  }
}

Use the harness-specific syntax for remote Streamable HTTP MCP servers. The important requirements are the server URL and the X-API-Key HTTP header.

Tools

read_x12

Parses raw X12 EDI content into structured JSON.

Inputs:

  • content (string, required): Raw X12 interchange content. Must contain an ISA segment.
  • include997 (boolean, optional): Include a generated 997 Functional Acknowledgment. Defaults to false.

Output:

  • Structured content equivalent to the JSON response from POST /api/v1/read/x12.
  • Serialized JSON text for MCP clients that only consume text content.

Read failures are returned as MCP tool execution errors with the operation response included.

write_x12

Generates raw X12 EDI content from structured X12 JSON.

Inputs:

  • content (object, required): Structured X12 JSON with ISA, Groups, each group's GS, and Transactions.

Output:

  • Structured content equivalent to the JSON response from POST /api/v1/write/x12.
  • Serialized JSON text for MCP clients that only consume text content.

Write failures are returned as MCP tool execution errors with the operation response included.

validate_x12

Validates raw X12 EDI content against supported X12 specifications.

Inputs:

  • content (string, required): Raw X12 interchange content. Must contain an ISA segment.

Output:

  • Structured content equivalent to the JSON response from POST /api/v1/validate/x12.
  • Serialized JSON text for MCP clients that only consume text content.

An invalid X12 document is a successful tool result with isValid: false, validation errors, and warnings. Authentication, rate limit, transport, and server failures are returned as MCP request or tool errors.

Companion Skills

The MCP server provides the callable tools. The downloadable skills provide the methodology: when to call each tool, how to preserve X12 input, how to interpret the response, and how to recover when something fails.

Download the current X12 skills from the AI Agents page:

  • x12-reader for read_x12 parsing, inspection, extraction, and optional 997 generation.
  • x12-validator for validate_x12 pass/fail, compliance, and rejection triage.
  • x12-writer for write_x12 structured JSON to raw X12 generation.

Install the skill folders into your harness-specific skills directory. Keep API keys in the harness MCP configuration, not in skill files.

Local Development

Start the development stack with Docker Compose, then point the harness at the local MCP server:

{
  "mcpServers": {
    "neutron-edi-local": {
      "url": "http://localhost:5100/mcp",
      "headers": {
        "X-API-Key": "${NEUTRON_EDI_API_KEY}"
      }
    }
  }
}

The local server uses the same MCP tools and authentication behavior as production.

PreviousAuthentication