SignalEDI MCP Server

SignalEDI MCP Server

A Model Context Protocol server that exposes the SignalEDI Core API (/api/v1) as tools, so AI clients — Claude Desktop, Cursor, Windsurf, Claude Code, and any other MCP host — can parse, validate, send, and inspect X12 EDI documents directly in a conversation or agent loop.

It is mostly a thin adapter over the hosted SignalEDI engine, with a few local X12 helper surfaces for demo mode and model grounding: synthetic templates, a small validation/error dictionary, prompts, and bundled resources. The hosted API remains the source of truth for production parse, validate, send, transaction, kit, and QuickBooks flows.

Discoverable in the official MCP Registry and the directories that crawl it (Smithery, Glama, mcp.so, PulseMCP). The server.json in this folder is the registry manifest; package.json carries the matching mcpName ownership marker.

Tools

Bad arguments and API errors are returned as structured MCP tool errors with stable codes (so the model can recover from them) rather than crashing the server. Results include both backwards-compatible text content and native structuredContent.

Mutation safety

Tools that send EDI, write to QuickBooks, or disconnect QuickBooks require both confirm: true and a unique idempotencyKey (at least eight characters). The server adds a request id, tool name, and idempotency header to outbound API calls. Dry-run QuickBooks export remains available without confirmation. Tool listings advertise read-only versus destructive behavior and required capability scopes.

The client rejects non-HTTPS base URLs except for localhost, caps EDI payloads at 64 KiB, retries transient failures within a total deadline, and emits redacted per-tool latency/success metrics to stderr. Set SIGNALEDI_MCP_TELEMETRY=0 to disable local metric lines.

Quick start

1. Try without a key (demo mode). Run npx -y @signaledi/mcp-server with no env vars — parse_edi and validate_edi call the public playground; generate_test_document, explain_edi_error, lookup_x12, and the alias tools use local X12 templates/dictionary data. Keyed tools return a structured demo_mode error with a link to create a key.
2. Add a platform key for production flows. Create a workspace key with the platform scope at signaledi.com/console/keys and set SIGNALEDI_API_KEY.

One-click install

• Cursor: Install in Cursor (same deeplink as the developer site chip).
• Claude Code: claude mcp add signaledi -- npx -y @signaledi/mcp-server

Claude Desktop / Claude Code

Add to your MCP config (claude_desktop_config.json, or .mcp.json for Claude Code):

{
  "mcpServers": {
    "signaledi": {
      "command": "npx",
      "args": ["-y", "@signaledi/mcp-server"],
      "env": {
        "SIGNALEDI_API_KEY": "sk_live_…"
      }
    }
  }
}

Cursor / Windsurf

Same shape under the editor's MCP settings (command: npx, args: ["-y", "@signaledi/mcp-server"], and the SIGNALEDI_API_KEY env var).

Demo mode

Without a key, the server runs in demo mode (stderr notice): parse_edi and validate_edi call the public playground; local template/dictionary tools run without network; keyed tools return JSON { "error": "demo_mode" }; successful demo results append — demo mode; responses rate-limited.

Configuration

The server speaks JSON-RPC over stdout; all logs go to stderr, so it never corrupts the protocol channel.

Example prompts

"Parse this 850 and tell me the PO number and ship-to." (paste raw EDI) "Validate this interchange and list any structural errors." "Show my last 10 transactions and flag any that missed SLA." "Send an 810 invoice to partner acme-co with these line items…"

Local development

node test.mjs        # dependency-free unit tests (mock fetch, no network)
SIGNALEDI_API_KEY=… npm start   # run the stdio server against the live API

The client (src/client.mjs) and tools (src/tools.mjs) are pure and unit-tested; src/index.mjs is the only file that depends on the MCP SDK.

How it fits

MCP client (Claude/Cursor/…) ⇄ @signaledi/mcp-server (stdio) ⇄ SignalEDI Core API (/api/v1)
                                      └ local X12 templates/dictionary/resources for demo + guidance

See the SDK for a programmatic TypeScript client and docs/openapi/v1 for the full API reference.

GitHub mirror

The public GitHub repo SignalEDI/mcp-server mirrors this folder only. The GitLab monorepo stays the source of truth; the mirror updates on each npm publish (see MIRROR.md and the operator runbook docs/internal/runbooks/GITHUB_MCP_MIRROR.md).

Examples

Run from this directory: node examples/parse-demo.mjs

Issue templates for the GitHub repo live under examples/.github/ISSUE_TEMPLATE/ (copied to repo root on mirror sync). Layout: examples/github-mirror-layout.md.

Mirror security checklist

Before every mirror push:

• No internal URLs, API keys, engine code, or employee/customer data in the tree
• Examples use synthetic EDI only; transcripts are fictional
• Badges and links point at public npm, MCP registry, and signaledi.com only