> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stateset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# EDI MCP Server

> Expose the StateSet EDI gateway to Claude and other agents as 117 callable tools over MCP.

# EDI MCP Server

A [Model Context Protocol](https://modelcontextprotocol.io) server that exposes the StateSet
EDI gateway as agent-callable tools. It is a thin, **stateless** wrapper over the REST API —
point it at a running gateway with a bearer token and an MCP host (Claude Desktop, Claude Code)
can drive EDI flows directly.

## What it exposes

**117 tools**, grouped by area:

| Area                          | Tools                                                                                                                                                 |
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| **System / trust**            | Health, X12 capabilities, signing-key discovery, event verification                                                                                   |
| **Partners / tenants**        | List/get/upsert partners, overlays, partner API keys, tenant registry, tenant API-key lifecycle                                                       |
| **Inbound EDI**               | Raw X12/EDIFACT processing, partner-explicit inbound processing, validation, parsing, AS1/AS2 ingress helpers                                         |
| **Outbound EDI**              | X12 `204`, `270`, `810`, `832`, `846`, `855`, `856`, `865`, `940`, `943`; EDIFACT `INVOIC` and `DESADV`                                               |
| **Labels / artifacts**        | Shipment labels, carton labels, level labels, packing slips, packing-slip PDF, commercial invoice, postal declarations, UBL e-invoices and validation |
| **Documents / evidence**      | Document list/detail, document and reference evidence bundles, lifecycle trace, replay-by-reference, manual entry, single and bulk reprocess          |
| **Operations**                | Reconciliation, business reconciliation, monitoring/evaluate, status board, analytics/export, fulfillment, usage, outbox/flush, deadletter/replay     |
| **Delivery / transport**      | Delivery list, redeliver single/bulk, transport operations, network readiness, VAN providers/status/poll, network mailbox, AS2 identity/MDN           |
| **Revenue recovery**          | Deduction list/detail/capture/evidence/categorize/dispute/resolve                                                                                     |
| **Onboarding / guides**       | Onboarding lifecycle, standard and custom certification, guide snapshot/validate/versions/diff/rollback, template list/get/publish/instantiate        |
| **Catalog / adapters / SDK**  | Catalog list/ingest, adapter list/plan/confirmed execution, connector manifest validate/certify                                                       |
| **Retailer profiles / leads** | Retailer profiles, profile samples, certification packs, checks, lead capture and list                                                                |
| **Workflow demos**            | `edi_demo_order_to_invoice_flow` runs the complete sandbox 850 → 997 → labels → 856 → 810 → retailer 997 acceptance loop                              |

## Build

```bash theme={null}
cd mcp
npm install
npm run build      # → dist/index.js
```

## Configure

Two environment variables:

| Variable        | Default                 | Meaning                                                    |
| --------------- | ----------------------- | ---------------------------------------------------------- |
| `EDI_API_BASE`  | `http://localhost:8480` | Gateway base URL                                           |
| `EDI_API_TOKEN` | —                       | Admin bearer token, or a partner API key for scoped access |

### Claude Desktop

Add to `claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "stateset-edi": {
      "command": "node",
      "args": ["/absolute/path/to/stateset-edi/mcp/dist/index.js"],
      "env": {
        "EDI_API_BASE": "https://your-edi-host",
        "EDI_API_TOKEN": "your-admin-token"
      }
    }
  }
}
```

### Claude Code

```bash theme={null}
claude mcp add stateset-edi \
  --env EDI_API_BASE=https://your-edi-host \
  --env EDI_API_TOKEN=your-admin-token \
  -- node /absolute/path/to/stateset-edi/mcp/dist/index.js
```

## Try it

With a gateway running and the environment set, ask the host:

> List our trading partners, then process this 850 and show me the signed event it produced.

> Show the deductions summary and dispute the largest open chargeback.

> Run standard certification for `walmart-us` and tell me if it published a template.

> Run `edi_demo_order_to_invoice_flow` and summarize the generated PO, shipment, invoice,
> carton labels, and final 856/810 reconciliation status.

## Notes

* **Transport is stdio** — the universal local form. The same tool definitions can be served
  over Streamable HTTP for a hosted/remote MCP callable by cloud agents and deployable to
  Kubernetes alongside the gateway.
* The server holds **no state** and stores no credentials beyond the environment variable.
  Every call is a direct, authenticated request to the gateway.
* Scope an agent down by giving it a **partner API key** instead of the admin token — it will
  only reach that partner's own routes.

## Related

* [Overview](/stateset-edi/overview)
* [Operations](/stateset-edi/operations)
* [MCP Integration Guide](/guides/mcp-integration-guide)