@ssig-it/infinigate-mcp-server

v0.4.3

Published

11 days ago

MCP server for the Infinigate Reseller API

0High
0Medium
0Low

paulkatio

mcp model-context-protocol infinigate reseller-api claude llm

Infinigate MCP Server

Connect any AI agent to the Infinigate Reseller API — search products, manage invoices, accept quotes, place orders.

Quick Start · Tools · Self-Hosting · Development · Contributing

Auch auf Deutsch verfügbar: README.de.md

About

infinigate-mcp-server is a production-grade Model Context Protocol server that exposes the Infinigate Reseller API to AI agents such as Claude, ChatGPT, and any other MCP-compatible client. It is built and maintained by SSIG-IT GmbH for managed service providers (MSPs) and value-added resellers in the DACH region — and ships with tools designed for real workflows, not 1:1 API mirroring.

Features

10 workflow-oriented tools covering product search, invoice analytics, quote management, and order placement
LLM-optimized: careful tool descriptions, slim snake_case responses, and actionable error hints
Production-ready: token caching with concurrent-refresh deduplication, automatic 401 retry, structured logging with credential redaction
Dual transport: stdio for local use (Claude Desktop, VS Code) and Streamable HTTP for self-hosting
Type-safe end to end: every input is validated with Zod; every response is shaped to drop nulls and truncate long text
Well tested: 65+ unit tests with mocked API responses, zero network calls in CI
Bilingual docs: English and German (Infinigate is DACH-focused, so deutsche Doku ist kein Nice-to-have)

Quick Start

[!NOTE] You need Infinigate API credentials — see Prerequisites below.

Add this to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "infinigate": {
      "command": "npx",
      "args": ["-y", "@ssig-it/infinigate-mcp-server"],
      "env": {
        "INFINIGATE_API_KEY": "...",
        "INFINIGATE_CLIENT_ID": "...",
        "INFINIGATE_CLIENT_SECRET": "..."
      }
    }
  }
}

Restart Claude Desktop. You should see the Infinigate tools appear in the tools palette.

claude mcp add infinigate npx -y @ssig-it/infinigate-mcp-server

Then set your credentials as environment variables in the MCP config.

docker run -d --name infinigate-mcp \
  -e MCP_TRANSPORT=http \
  -e MCP_AUTH_TOKEN=your-long-random-token \
  -e INFINIGATE_API_KEY=... \
  -e INFINIGATE_CLIENT_ID=... \
  -e INFINIGATE_CLIENT_SECRET=... \
  -p 3000:3000 \
  ghcr.io/ssig-it/infinigate-mcp-server:latest

The HTTP transport exposes a Bearer-protected MCP endpoint suitable for team-wide use behind a reverse proxy. See Self-Hosting for the full setup.

Prerequisites

An active Infinigate reseller account
API credentials (INFINIGATE_API_KEY, INFINIGATE_CLIENT_ID, INFINIGATE_CLIENT_SECRET) — request them via ID Connect
Node.js 22+ (for npm/npx) — or just Docker

Available Tools

| Tool | Type | Description | |---|---|---| | infinigate_search_products | Read | Free-text catalog search across SKU and description, with filters for vendor, product type, and pricing tier | | infinigate_get_products_by_sku | Read | Lookup up to 50 products by exact SKU, auto-detecting Infinigate vs. vendor SKU format | | infinigate_list_manufacturers | Read | List all available vendors in your catalog, with optional name filter | | infinigate_list_invoices | Read | List invoices and/or credit memos by date range, vendor, or buyer reference | | infinigate_get_invoice | Read | Full invoice details including line items, addresses, and per-license MSP usage | | infinigate_list_quotes | Read | List quotes by date range with optional status filter | | infinigate_get_quote | Read | Full quote details including document_revision (required for accept/reject) | | infinigate_accept_quote | Write | Accept a quote and convert it into a binding purchase commitment | | infinigate_reject_quote | Write | Reject a quote with optional reason | | infinigate_create_order | Write | Place a new purchase order directly, bypassing the quote flow |

Legend: Read = safe, idempotent. Write = destructive, hosts should prompt the user for explicit confirmation before invoking.

[!TIP] For the reasoning behind tool shapes and descriptions, see docs/TOOL_DESIGN.md (Coming in Phase 6).

Configuration

| Variable | Required | Default | Description | |---|---|---|---| | INFINIGATE_API_KEY | Yes | — | Portal API key (sent as API-KEY header) | | INFINIGATE_CLIENT_ID | Yes | — | OAuth client ID | | INFINIGATE_CLIENT_SECRET | Yes | — | OAuth client secret | | INFINIGATE_BASE_URL | — | https://api.infinigate.com | API base URL | | MCP_TRANSPORT | — | stdio | stdio or http | | MCP_HTTP_PORT | — | 3000 | Port for the HTTP transport | | MCP_HTTP_HOST | — | 0.0.0.0 | Bind address for the HTTP transport | | MCP_AUTH_TOKEN | Conditional | — | Required if MCP_TRANSPORT=http. Bearer token for protecting the endpoint | | INFINIGATE_TOKEN_TTL_SECONDS | — | 240 | Token cache TTL (Infinigate tokens live 5 min; default gives 60 s buffer) | | INFINIGATE_REQUEST_TIMEOUT_MS | — | 15000 | Per-request timeout | | INFINIGATE_MAX_RETRIES | — | 2 | Retries on transient failures | | DEFAULT_PAGE_SIZE | — | 20 | Default page size for list tools | | MAX_PAGE_SIZE | — | 100 | Maximum allowed page size | | LOG_LEVEL | — | info | fatal / error / warn / info / debug / trace | | LOG_FORMAT | — | pretty | pretty (dev) or json (production) |

[!WARNING] Never commit credentials. Use a gitignored .env file during development or your platform's secret manager in production. The server redacts credentials automatically from log output.

Architecture

┌──────────────────────────────────────────────────────┐
│  LLM Client  (Claude Desktop, VS Code, MetaMCP)      │
└─────────────────────────┬────────────────────────────┘
                          │  MCP Protocol
                          ▼
┌──────────────────────────────────────────────────────┐
│  Transport Layer  —  stdio  |  Streamable HTTP       │
└─────────────────────────┬────────────────────────────┘
                          ▼
┌──────────────────────────────────────────────────────┐
│  MCP Server Core                                     │
│  Tool Registry · Zod Validation · Error Handler      │
└─────────────────────────┬────────────────────────────┘
                          ▼
┌──────────────────────────────────────────────────────┐
│  Infinigate API Client                               │
│  Auth Manager · Retry · Response Shaper              │
└─────────────────────────┬────────────────────────────┘
                          │  HTTPS  +  Bearer  +  API-KEY
                          ▼
                  api.infinigate.com

Key design decisions:

Stateless HTTP transport in production — no session state in the server
In-memory token cache with concurrent-refresh deduplication (four tools calling at once → one /authorization/token request)
Single-reseller instance — credentials come from the environment; no multi-tenancy
Bearer auth on the MCP endpoint itself (distinct from the upstream Infinigate bearer), so the HTTP transport can be safely exposed via a reverse proxy

Self-Hosting

Docker Compose (recommended)

services:
  infinigate-mcp:
    image: ghcr.io/ssig-it/infinigate-mcp-server:latest
    restart: unless-stopped
    environment:
      MCP_TRANSPORT: http
      MCP_HTTP_PORT: 3000
      MCP_AUTH_TOKEN: ${MCP_AUTH_TOKEN}
      INFINIGATE_API_KEY: ${INFINIGATE_API_KEY}
      INFINIGATE_CLIENT_ID: ${INFINIGATE_CLIENT_ID}
      INFINIGATE_CLIENT_SECRET: ${INFINIGATE_CLIENT_SECRET}
      LOG_FORMAT: json
      LOG_LEVEL: info
    ports:
      - "127.0.0.1:3000:3000"

Behind a Reverse Proxy (Caddy)

mcp.example.com {
    handle_path /mcp/infinigate* {
        reverse_proxy 127.0.0.1:3000 {
            max_conns_per_host 4
        }
    }
}

MetaMCP Integration

Add the endpoint URL in MetaMCP, use the Bearer token from MCP_AUTH_TOKEN, and tools are auto-discovered via the standard MCP tools/list call.

Tool Design Philosophy

Tool shapes are guided by Anthropic's Writing effective tools for AI agents. Concretely, that means:

Workflows, not endpoints. infinigate_list_invoices accepts document_type: 'both' and merges results — the agent doesn't need to know there are two API endpoints.
snake_case everywhere. Easier for models to tokenize and reason about than camelCase or PascalCase.
Slim responses. Null and undefined fields are dropped entirely; long descriptions are truncated to 200 chars with a description_truncated: true flag.
Errors are structured, not stringified. Every failure returns { error: true, code, message, hint } with a concrete next-step suggestion.

See docs/TOOL_DESIGN.md (Coming in Phase 6) for the full design rationale.

Development

git clone https://github.com/SSIG-IT/infinigate-mcp-server.git
cd infinigate-mcp-server
npm install
cp .env.example .env   # fill in your Infinigate credentials
npm run dev            # stdio transport with hot reload
npm test               # run the full test suite
npm run lint           # ESLint + Prettier check
npm run typecheck      # strict TypeScript check
npm run build          # production build via tsup

The project uses Vitest for tests, tsup for builds, and strict TypeScript with noUncheckedIndexedAccess. No runtime dependency on network access in tests — every API call is mocked.

More in docs/DEVELOPMENT.md (Coming in Phase 6).

Roadmap

[x] Phase 1 — Core infrastructure (auth, client, error mapping)
[x] Phase 2 — Read tools: products, SKU lookup, manufacturers
[x] Phase 3 — Read tools: invoices, quotes
[x] Phase 4 — Write tools: accept/reject quotes, create orders (live-verified against sandbox; awaiting one final destructive test against a real test quote before release)
[x] Phase 5 — HTTP transport, Docker image, CI/CD
[ ] Phase 6 — Public release: npm publish, GHCR image, full docs
[ ] Phase 7 — Customer-management endpoints (EndCustomerData, AliasMapping)

Release schedule

| Version | Scope | Trigger | |---|---|---| | v0.4.0 | Phase 4 write tools (accept/reject quote, create order) + Phase 5 HTTP transport + Docker | Ready — pending final manual write-tool test against a real sandbox quote | | v1.0.0 | Phase 6 — public, stable, npm + GHCR published | When all 10 tools are live-tested end-to-end and docs are complete |

Versioning is driven by release-please from Conventional Commits. Maintainers do not hand-edit CHANGELOG.md or the package.json version — release-please opens a release PR; merging it tags and triggers npm + GHCR publish.

Contributing

Contributions are welcome. See CONTRIBUTING.md for the workflow, coding standards, and how to add a new tool. We use Conventional Commits and keep every PR green on lint, typecheck, and tests.

Bug Reports

Found a bug or security issue? Open an issue on GitHub or contact [email protected].

License

MIT — see LICENSE.

Built by SSIG-IT GmbH. Not affiliated with or endorsed by Infinigate Group AG.

Acknowledgments

Built on the Model Context Protocol
Tool design guided by Anthropic's best practices
Inspired by other high-quality MCP servers in the modelcontextprotocol/servers ecosystem