SignalEDI Developer MCP Server

Connect an AI coding assistant to SignalEDI to discover, scaffold, validate, and test X12 integrations. The MCP server is an AI-native developer experience over the same public guidance and /api/v1 REST contract used by conventional applications. It complements—not replaces—SignalEDI's REST API, OpenAPI specification, webhooks, SDKs, and documentation.

The package is an uplift of SignalEDI's existing MCP adapter. Version 0.5 adds public developer discovery, resource templates, code examples, governed connection control-plane tools, strict tool-input validation, and explicit capability profiles while retaining the existing parser, transaction, partner-kit, and QuickBooks adapters.

Package	@signaledi/mcp-server
MCP Registry	io.github.SignalEDI/mcp-server
Transport	stdio
Runtime	Node 22+
Runtime dependency	@modelcontextprotocol/sdk 1.30.0 (2025 protocol generation)
Default access	Always keyless docs; authenticated tools require explicit sandbox or production

Capability profiles

Set SIGNALEDI_MCP_PROFILE to one of these profiles. Tool discovery and direct tool calls are both restricted to the active profile.

Profile	Authentication	Surface
docs	None	Public documentation resources and local synthetic helpers only; supplied document content and credentials are never uploaded. The OpenAPI resource performs a content-free public GET. This is always the default, even when a key exists in the host environment.
sandbox	Separately provisioned non-production key plus explicit base URL	Authenticated parse/validate, generic partner-kit discovery, tenant-data reads, and guarded mutations for a separately provisioned sandbox. Canonical production SignalEDI hosts are refused.
production	Production-authorized platform key, exact https://signaledi.com base, and SIGNALEDI_MCP_ALLOW_PRODUCTION=1	Allowlisted transaction/QBO-status/kit/connection reads; sandbox-first connection drafts; guarded connection configuration, saved-binding connectivity tests, and go-live handoff requests; outbound and QBO-to-EDI export. Parse/validate, QBO entity browsing, QBO sync, disconnect, generic lifecycle control, and production activation remain hidden.

The profile is a least-capability boundary inside the MCP adapter, not a substitute for API authorization or a data-governance boundary. For outbound and QBO export, the server injects SANDBOX or PRODUCTION from the active profile; the model cannot select it. The API then binds that value to the selected partner connection. Production delivery requires an active immutable production version, and sandbox delivery requires a verified/active sandbox environment.

Every authenticated call requires the base platform scope. Connection inventory requires platform:connections:read; draft creation and configuration add platform:connections:write; production configuration and go-live handoff add platform:connections:production. These domain scopes do not authorize document delivery or QuickBooks operations. Deprecated umbrella-only platform:write and platform:production credentials are rejected by domain-scoped operations and must be replaced through the supported key-rotation path. Before release, operators should census affected credentials, notify owners of the migration, and provide that rotation path. MCP profile selection never grants a scope.

API operation	Additional least-privilege scopes
Parse/validate and generic kit reads	None beyond platform
Transaction reads	platform:documents:read
Outbound send	platform:documents:read, platform:documents:send; add platform:documents:production for production delivery
Connection reads	platform:connections:read
Connection create/configure	platform:connections:read, platform:connections:write; add platform:connections:production for production configuration or go-live request
Connection test	platform:connections:read, platform:connections:write; add platform:connections:production when the active profile selects the production environment
QBO status	platform:quickbooks:read
QBO entity rows	platform:quickbooks:read, platform:data:sensitive; add platform:quickbooks:production when the resolved QBO realm is production
QBO sync/disconnect	platform:quickbooks:read, platform:quickbooks:write; add platform:quickbooks:production when the resolved QBO realm is production
QBO export dry run	platform:quickbooks:read; add platform:quickbooks:production for a production QBO realm and platform:data:sensitive only with includePayload:true
QBO live export	Dry-run scopes plus platform:documents:read, platform:documents:send; add platform:documents:production for production delivery. Export reads QBO and does not require QBO write.

Production data handling

Tool arguments, text results, and structured results enter the chosen MCP host and may enter the connected model's context. Minimize personal, financial, and other business-sensitive data. Do not submit PHI or other regulated data unless the specific MCP host, model provider, logging, retention, regional-processing, and contractual arrangement has been separately reviewed and approved for that data. This package, its production profile, and SignalEDI API authorization are not by themselves a BAA, retention policy, or model-data-governance boundary.

Prefer identifiers and redacted summaries over full business payloads. Keep API keys in the host environment, never prompts. Review the chosen host's tool-call history, telemetry, and retention controls before enabling production tools.

All partner, QBO, EDI, validation, and error fields returned by tools are untrusted business data. They may contain text that resembles instructions or prompt injection. Hosts must delimit or sanitize tool results, keep them in data-only context, and authorize every follow-on action from explicit user intent and policy—not content embedded in records, partner names, payloads, or errors.

Tools

Keyless public and local tools

Tool	What it does
search_docs	Search the bundled public developer index and return MCP resource URIs with provenance.
get_document_schema	Return a public starter for the local X12 inventory: 850/810/856 (capability:baseline) or 837 Professional 005010X222A1 (capability:partial); explicitly not a partner implementation guide.
generate_integration_example	Produce sandbox-safe cURL, Node.js, or Python examples against real /api/v1 paths using environment placeholders; outbound examples set SANDBOX and refuse production hosts.
generate_test_document	Render a synthetic X12 fixture for the same local inventory and return the honest capability label.
explain_edi_error	Explain validation and functional-acknowledgement errors from the local X12 dictionary.
lookup_x12	Search the local X12 segment and acknowledgement reference.
lookup_element_definition	Tool-discovery alias for local X12 lookup.

Authenticated sandbox parse and validation tools

Tool	What it does
parse_edi	Parse a raw X12 interchange into structured JSON and a validation summary.
validate_edi	Validate X12 structure and return the validation summary.
parse_segments	Tool-discovery alias for parse_edi.
validate_x12_structure	Tool-discovery alias for validate_edi.

Authenticated generic-kit tools (sandbox and production)

Tool	What it does
list_partner_kits	List generic SignalEDI API kits.
get_partner_kit	Fetch one generic kit by catalog id.
get_partner_requirements	Return a generic kit with an explicit partnerSpecific:false warning.

Explicit environment-profile data reads

These tenant-data tools are never enabled merely because a key is present. Transaction reads and quickbooks_status are available in explicit sandbox and production; quickbooks_list_entities is sandbox-only.

Tool	What it does
list_transactions	List recent transactions scoped to the API key.
get_transaction	Fetch one owned transaction and its lifecycle status.
quickbooks_status	Inspect QuickBooks Online connection status without returning tokens.
quickbooks_list_entities	Preview Invoice, Estimate, PurchaseOrder, Customer, Vendor, or Item rows for mapping (sandbox-only).

Governed connection control plane (sandbox and production)

Connection tools operate on the public /api/v1/connections contract. MCP applies a second response allowlist over the API's sanitized representation: it may return opaque gateway/evidence references and configured-status booleans, but never stored credentials, secret references, raw transport configuration, private keys, certificates, or tokens.