Stanza MCP Server (@stanzaapi/mcp)

Model Context Protocol (MCP) server for Stanza enterprise APIs. It gives Claude Desktop, Cursor, Windsurf, and any MCP-capable AI agent 13 deterministic B2B tools — IBAN and BIC/SWIFT validation, ANSI X12 healthcare EDI parsing (837P/835/270/271), ISO 20022 payment XML (pacs.008/pain.001/camt.053), GS1 barcode and Digital Link decoding, ISO 6346 container checks, IATA air waybill validation, LEI and VAT verification, Peppol BIS Billing 3.0 and Factur-X/ZUGFeRD EN 16931 e-invoice validation, FDA DSCSA verification, UDI decoding, and EU CBAM calculations — without the model guessing checksums, regexes, or code lists.

The server is a thin stdio client: every tool call is executed by the live Stanza public edge gateway at https://api.stanzaapi.com/<engine> and returned as the authoritative JSON envelope.

Quick start

Run the server directly (no install):

npx -y @stanzaapi/mcp

Claude Desktop

Add this to claude_desktop_config.json:

{
  "mcpServers": {
    "stanza": {
      "command": "npx",
      "args": ["-y", "@stanzaapi/mcp"],
      "env": {
        "STANZA_API_KEY": "nk_live_..."
      }
    }
  }
}

Cursor

Add the same server block to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global).

VS Code

Add to .vscode/mcp.json:

{
  "servers": {
    "stanza": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@stanzaapi/mcp"],
      "env": {
        "STANZA_API_KEY": "nk_live_..."
      }
    }
  }
}

Restart the client after editing its configuration. A free API key takes under a minute to create at stanzaapi.com/dashboard.

One-click install (MCPB bundle)

Claude Desktop installs local MCP servers from an .mcpb bundle. Build one from this repository:

node scripts/build-mcpb.mjs   # -> packages/mcp-server/dist/server.mcpb

Open server.mcpb with Claude Desktop and enter your nk_live_... key in the install dialog; the bundle asks only for the API key, while the gateway URL and timeout keep their defaults. The same artifact is what Smithery's local (MCPB) publishing flow distributes (smithery mcp publish <artifact> -n <owner>/stanza-enterprise-apis).

Configuration

| Setting | CLI flag | Environment variable | Default | | --- | --- | --- | --- | | API key | --api-key <key> | STANZA_API_KEY | none (tools return setup guidance) | | Gateway base URL | --base-url <url> | STANZA_BASE_URL | https://api.stanzaapi.com | | Request timeout | --timeout-ms <n> | STANZA_TIMEOUT_MS | 5000 (range 1000–30000) |

CLI flags win over environment variables. --base-url must be https://, except for localhost, 127.0.0.1, or [::1] during local development; embedded credentials, paths, queries, and private network hosts are rejected. --help and --version print to stdout and exit; all operational logs go to stderr so the JSON-RPC channel stays clean.

Tool catalog

| Tool | Engine | What it does | | --- | --- | --- | | validate_iban | iban-validator | IBAN (ISO 13616) MOD-97-10 checksum, country structure, BBAN parsing, SEPA reachability, print/electronic formats; optional BIC/SWIFT (ISO 9362) check. | | parse_x12_edi | x12-parser | Parse or validate ANSI X12 837P claims, 835 remittance advice, and 270/271 eligibility transactions into structured JSON with SNIP levels 1–4. | | decode_gs1 | gs1-decoder | Decode GS1-128, DataMatrix, FNC1/bracketed element strings and GS1 Digital Link URIs into AI fields (GTIN, lot, serial, expiry). | | validate_iso6346_container | container-validator | ISO 6346 container number (BIC prefix, category, serial, modulo-11 check digit); optional size/type code. | | parse_iso20022 | iso20022-parser | Parse or validate pacs.008, pain.001, and camt.053 XML with automatic message-type detection. | | calculate_cbam | cbam-carbon | EU CBAM (Regulation (EU) 2023/956) embedded emissions and liability from CN code, origin, mass, route, electricity, and precursors. | | validate_lei | lei-validator | LEI (ISO 17442) checksum and format; optional live GLEIF issuance status. | | validate_vat | vat-validator | EU/UK VAT number syntax and checksum with standard/reduced rates; optional live VIES/HMRC verification. | | validate_iata_awb | iata-validator | IATA air waybill prefix, serial, and modulo-7 check digit (Resolution 600a). | | decode_udi | udi-decoder | UDI decoding for GS1, HIBCC, and ICCBBA carriers with FDA GUDID / EU MDR checks; optional live GUDID lookup. | | validate_peppol | peppol-validator | Peppol BIS Billing 3.0 UBL/CII e-invoice validation and extraction against CEN TC 434 rules. | | validate_dscsa | pharma-dscsa | FDA DSCSA verification from a DataMatrix barcode or the GTIN + serial + lot + expiration element set. | | validate_facturx | factur-x-validator | Factur-X, ZUGFeRD 2.x, and XRechnung CII e-invoice validation against EN 16931 rules (BR-01..BR-65) with profile detection and extracted invoice JSON. |

Each tool declares read-only, idempotent, open-world annotations. Inputs are validated against strict Zod schemas before any network call.

Behavior without an API key

The handshake and tools/list always work. tools/call returns a structured isError payload:

{
  "success": false,
  "code": "UNAUTHORIZED",
  "status": null,
  "error": "No STANZA_API_KEY configured.",
  "hint": "Set STANZA_API_KEY in your MCP client configuration, or create a free API key at https://stanzaapi.com/dashboard."
}

hk_live_ HIPAA-plane keys are rejected up front with WRONG_PLANE_KEY; use a public edge nk_live_ key with https://api.stanzaapi.com.

Error handling

| Condition | code | | --- | --- | | Structurally invalid tool arguments | JSON-RPC -32602 from the SDK (Zod issues) | | Cross-field argument rule (DSCSA) | VALIDATION_ERROR | | Gateway HTTP 400 | VALIDATION_ERROR | | Missing or invalid key (401) | UNAUTHORIZED | | Forbidden (403) | FORBIDDEN | | Unknown route or identifier (404) | NOT_FOUND | | Payload above the 512KB API limit (413) | PAYLOAD_TOO_LARGE | | Rate limit or quota (429) | RATE_LIMITED / QUOTA_EXCEEDED with retry_after | | Gateway 5xx or non-JSON body | INTERNAL_ERROR | | Connection failure | NETWORK_ERROR | | AbortSignal.timeout expiry | TIMEOUT |

Every failure is a compact JSON text block with isError: true so the calling model can correct its arguments or tell the user what to do next.

Adding a new tool

Each tool is one file, so a new engine ships as a one-file change plus a test row:

1. Create src/tools/<slug>.ts exporting a frozen ToolSpec:

   import { object, string } from "zod";
   import { argumentError, type ToolSpec } from "./spec";
   
   const schema = object({ example: string().min(1).describe("Input description") });
   
   export const exampleTool: ToolSpec = {
     name: "validate_example",
     title: "Validate Example",
     description: "Keyword-rich description naming the standard and output shape.",
     inputSchema: schema.shape,
     buildRequests: (args) => {
       const parsed = schema.safeParse(args);
       if (!parsed.success) return argumentError(parsed.error);
       return {
         ok: true,
         plan: {
           calls: [
             {
               key: "example",
               request: {
                 method: "GET",
                 path: `/engine-slug/api/v1/example/${encodeURIComponent(parsed.data.example)}`,
               },
             },
           ],
         },
       };
     },
   };

2. Register it in src/tools/index.ts (TOOL_SPECS) and add the row to EXPECTED_TOOL_NAMES, EXPECTED_SCHEMA_KEYS, the builder tests, and the smithery.yaml tools list.

3. Run pnpm --filter @stanzaapi/mcp test — the registry, server, and metadata tests fail until all four places are updated.

The registry is a frozen lookup table; the server registers every entry automatically, so no server code changes are needed.

Development

pnpm --filter @stanzaapi/mcp check   # tsc --noEmit
pnpm --filter @stanzaapi/mcp test    # Vitest + 95% coverage gate
pnpm --filter @stanzaapi/mcp build   # esbuild bundle -> dist/index.mjs
pnpm --filter @stanzaapi/mcp deploy  # publish-ready build (prepublishOnly)

node scripts/build-mcpb.mjs builds the self-contained MCPB server bundle (dist/mcpb-server/index.mjs), parity-checks mcpb/manifest.json against the tool catalog, and packs dist/server.mcpb for Smithery and Claude Desktop.

The suite covers the stdio handshake, tools/list, tools/call success and failure paths against a real local HTTP oracle, argument validation, metadata consistency, and stdout purity.

Registry & discovery

• Smithery: smithery.yaml defines the stdio start command and API key configuration schema; local publishing uploads the MCPB bundle (node scripts/build-mcpb.mjs -> packages/mcp-server/dist/server.mcpb).
• MCP discovery manifest: stanzaapi.com/.well-known/mcp.json
• Agent index: stanzaapi.com/llms.txt · OpenAPI: stanzaapi.com/openapi.json

License

ISC. The published package contains only the compiled client, the bin shim, and documentation; parser and validation engines remain server-side.