Use with AI assistants (MCP) Last updated: 2026-11-12

What the server does

The tools work on file paths, so EDI files don't pass through the conversation. The server detects the format from the file. ediFabric Native supports X12 and HIPAA today; more standards follow.

Before you start

• Node.js 18 or later, from nodejs.org, for every client except Claude Desktop's one-click bundle, which includes everything.
• A supported platform: Windows x64, Linux x64 and arm64 with glibc 2.34 or later, or macOS on Apple silicon.
• A serial, optional to start: without one, the server uses the demo serial, which has a small daily quota and isn't for production. The free Community plan gives you your own; copy it from Your account.

Your EDI files stay on your machine: the server reads and writes them locally, and only in the folders you allow. The license check and the model downloads send your serial, and the transaction type and version, never the contents of your files. The assistant sees what the tools return: summaries, validation errors with the text of the segment each error is in, and any file you ask it to read. For files with personal or health data, check that your AI provider's terms cover that data.

Claude Code

As a plugin. In a Claude Code session, add the marketplace and install the plugin. It asks for your serial and keeps it in your system's credential store, and runs the server with Node directly:

/plugin marketplace add EdiFabric/edifabric-mcp
/plugin install edifabric@edifabric

As an MCP server. From a terminal, for every project (--scope user) or only the current one (--scope project, the default):

claude mcp add edifabric --scope user -e EDIFABRIC_SERIAL=YOUR_SERIAL -- npx -y @edifabric/mcp

On Windows, outside WSL, start npx through cmd:

claude mcp add edifabric --scope user -e EDIFABRIC_SERIAL=YOUR_SERIAL -- cmd /c npx -y @edifabric/mcp

For one project folder, add a .mcp.json file to it. Claude Code asks to approve the server the next time you open the folder. This one is for Windows; on macOS and Linux, use "command": "npx" and "args": ["-y", "@edifabric/mcp"]:

{
  "mcpServers": {
    "edifabric": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@edifabric/mcp"
      ],
      "env": {
        "EDIFABRIC_SERIAL": "YOUR_SERIAL",
        "EDIFABRIC_ALLOWED_DIRS": "C:\\EDI"
      }
    }
  }
}

The first start downloads the server and its native library, which can take up to a minute. To avoid a time-out, run npx -y @edifabric/mcp once in a terminal first, and stop it with Ctrl+C once it starts. Later starts take a couple of seconds. Check the connection by asking Claude to run get_status.

Claude Desktop

One click. Download edifabric-mcp-<version>.mcpb from the latest release, then open it in Claude Desktop in one of these ways:

• double-click the file (installing Claude Desktop registers the .mcpb file type);
• drag the file onto the Claude Desktop window;
• in Claude Desktop, go to Settings > Extensions > Advanced settings > Install Extension... and select the file.

Claude Desktop shows the extension; select Install, then enter your serial (or leave it empty for the demo serial) and the folder with your EDI files. The bundle includes Node.js support and the native libraries for every platform, so nothing else needs installing.

From the configuration file. In Claude Desktop, open Settings, Developer, Edit Config, and add the server to claude_desktop_config.json. Restart Claude Desktop afterwards:

{
  "mcpServers": {
    "edifabric": {
      "command": "npx",
      "args": [
        "-y",
        "@edifabric/mcp"
      ],
      "env": {
        "EDIFABRIC_SERIAL": "YOUR_SERIAL",
        "EDIFABRIC_ALLOWED_DIRS": "C:\\EDI"
      }
    }
  }
}

In Claude Desktop, give the tools full paths, such as C:\EDI\orders\po.edi.

Cursor

Add to Cursor installs it in one click. Or add this to .cursor/mcp.json in your project, or to ~/.cursor/mcp.json for every project:

{
  "mcpServers": {
    "edifabric": {
      "command": "npx",
      "args": [
        "-y",
        "@edifabric/mcp"
      ],
      "env": {
        "EDIFABRIC_SERIAL": "YOUR_SERIAL"
      }
    }
  }
}

VS Code and GitHub Copilot

Install in VS Code adds it in one click. Or add this to .vscode/mcp.json in your workspace. GitHub Copilot's agent mode then lists the tools:

{
  "servers": {
    "edifabric": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@edifabric/mcp"
      ],
      "env": {
        "EDIFABRIC_SERIAL": "YOUR_SERIAL"
      }
    }
  }
}

OpenAI Codex

Add this to ~/.codex/config.toml, for the Codex CLI and the Codex IDE extension:

[mcp_servers.edifabric]
command = "npx"
args = ["-y", "@edifabric/mcp"]
env = { EDIFABRIC_SERIAL = "YOUR_SERIAL" }

ChatGPT connects only to MCP servers hosted on the internet, so it can't run this local server.

Other MCP clients

Other MCP clients start the server with the same command, npx -y @edifabric/mcp, and the same environment variables. Gemini CLI (~/.gemini/settings.json), Windsurf (~/.codeium/windsurf/mcp_config.json), Cline and most others take the same mcpServers entry as Claude Desktop:

{
  "mcpServers": {
    "edifabric": {
      "command": "npx",
      "args": [
        "-y",
        "@edifabric/mcp"
      ],
      "env": {
        "EDIFABRIC_SERIAL": "YOUR_SERIAL"
      }
    }
  }
}

npm and the MCP Registry

The server is the npm package @edifabric/mcp. npx -y @edifabric/mcp downloads and starts it, and is what the client configurations above use. To install it once instead, and start it as edifabric-mcp:

npm install -g @edifabric/mcp

Then use "command": "edifabric-mcp" with no arguments in the client configuration. The package installs the ediFabric Native library for your platform through edifabric-x12.

The server is listed in the official MCP Registry as com.edifabric/edifabric-mcp. Clients and directories that read the registry, such as VS Code's MCP gallery, show it there.

Configuration

Set these as environment variables in the client's configuration, under env:

Models

Each transaction set is read and validated with a model for its type and version. By default, the server downloads the standard X12 and HIPAA models, sending the transaction type and version, never the contents of your files. describe_spec reads the same models.

To use local or custom models, such as ones you built in the EDI Spec Builder and downloaded for ediFabric Native, list them in a map.json and set EDIFABRIC_MAP to it. Each key is the transaction set and version from ST or GS, and location is relative to the map file:

{
  "default": "",
  "maps": {
    "837:005010X222A1": {
      "type": 1,
      "name": "model837P.json",
      "location": "."
    },
    "850:004010": {
      "type": 1,
      "name": "acme-850.json",
      "location": "models"
    }
  }
}

Transactions that aren't in the map still use the online models, unless EDIFABRIC_OFFLINE is true. See EDI models for the model format.

Licensing and quotas

How the license is checked depends on your plan. Set EDIFABRIC_SERIAL, and get_status shows which applies:

describe_spec and get_status don't read or write EDI, so they don't count as operations. Plans and quotas are on Pricing. The server is open source under the MIT license; ediFabric Native is licensed under the ediFabric EULA.

Try it

Ask the assistant in your own words. For example:

• Validate claims.837 at SNIP level 4 and explain each error.
• Validate every file in the inbound folder and give me a table of the results.
• Generate a 999 for every file in the inbound folder.
• Convert po.edi to JSON, change the quantity on line 2 to 12, and build it back to X12.
• Split batch.edi into one file per transaction.
• What does an 856 in 004010 look like? Create a sample one and validate it.

For sample files, the X12 examples have purchase orders, invoices, ship notices and HIPAA claims, remittances and enrollments.

Troubleshooting

• The server doesn't start the first time. The first start downloads the server, which can take longer than the client waits. Run npx -y @edifabric/mcp once in a terminal, stop it with Ctrl+C, and restart the client.
• A path is refused. The tools only use the allowed folders. Ask the assistant to run get_status, which lists them, and set EDIFABRIC_ALLOWED_DIRS to add yours.
• The quota is used up. The demo serial and the Community plan have daily quotas. Set EDIFABRIC_SERIAL to your own serial, or see Pricing.
• No model for a transaction. Check the transaction and version in ST and GS with describe_spec, or add a custom model with EDIFABRIC_MAP.
• Something else. Open an issue on GitHub, or contact us through the support portal.