invgate-mcp

A curated Model Context Protocol (MCP) server that exposes 12 read-only tools over stdio for InvGate Asset Management. Any MCP-compatible client (Claude Desktop, etc.) can query assets, people, computers, servers, software, and API health through natural language.

• Transport: stdio only (the universal default for local agents).
• Auth: OAuth2 client-credentials flow (scope=read), in-memory token cache with a 60-second expiry buffer and one-shot 401 retry.
• Validation: every tool input is validated with zod; invalid input returns a structured validation_error without calling the API.
• Resilience: HTTP, auth, and network failures are converted to MCP text content with isError: true — the server never crashes the host.
• Distribution: published to npm, runnable via npx invgate-mcp.

Install

# Run without installing
npx invgate-mcp

# Or install globally
npm install -g invgate-mcp
invgate-mcp

Configuration

The server reads three required environment variables at startup:

| Env var | Description | Example | |---|---|---| | INVGATE_BASE_URL | InvGate public API base URL (ends with /public-api/v2) | https://acme.invgate.net/public-api/v2 | | INVGATE_CLIENT_ID | OAuth2 client ID | my-client-id | | INVGATE_CLIENT_SECRET | OAuth2 client secret | my-client-secret |

If any are missing the server prints a descriptive error to stderr and exits with code 1.

The OAuth2 token endpoint is derived from INVGATE_BASE_URL by stripping the /public-api/v2 segment and appending /oauth2/token/, so https://acme.invgate.net/public-api/v2 → https://acme.invgate.net/oauth2/token/.

Claude Desktop config

Add invgate-mcp to your mcpServers block (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "invgate": {
      "command": "npx",
      "args": ["-y", "invgate-mcp"],
      "env": {
        "INVGATE_BASE_URL": "https://acme.invgate.net/public-api/v2",
        "INVGATE_CLIENT_ID": "your-client-id",
        "INVGATE_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Tools

| Tool | Input | Behavior | |---|---|---| | invgate_list_asset_types | none | Returns all asset types | | invgate_list_assets | page, per_page, asset_type_id, criteria | Paginated asset list with optional filters | | invgate_get_asset | asset_id (required) | Single asset by ID | | invgate_list_people | page, per_page, criteria | Paginated people list | | invgate_get_person | person_id (required) | Single person by ID | | invgate_get_person_assets | person_id (required), page, per_page | Assets assigned to a person | | invgate_list_computers | page, per_page, criteria | Assets of type "computer" | | invgate_get_computer | asset_id (required) | Single computer asset | | invgate_list_servers | page, per_page, criteria | Assets of type "server" | | invgate_get_server | asset_id (required) | Single server asset | | invgate_get_health | none | API connectivity status | | invgate_list_software | page, per_page, criteria | Paginated installed-software catalog |

Parameter mapping

Tool inputs use snake_case; the server maps them to the InvGate API query parameters. per_page → page_size, asset_type_id → asset_types. The criteria object maps to InvGate's nested syntax: { "name": "cont:MacBook" } becomes criteria[name]=cont:MacBook on the query string (op examples: cont, eq, startswith, …).

Results & errors

• Success: the raw JSON response body, pretty-printed, as MCP text content.
• Errors: structured JSON { "error": "...", "message": "...", "status": ... } as text content with isError: true. Types: validation_error, auth_error, api_error, network_error.

Development

npm install
npm run build       # tsup → dist/index.js (single ESM bundle)
npm run typecheck   # tsc --noEmit
npm test            # vitest run (59 tests, MSW for HTTP interception)
npm run test:coverage # vitest run --coverage (80% gate on src/**)
npm run dev         # tsx src/index.ts

Requires Node.js 20+ (uses native fetch).

License

MIT