{
  "markdown": "# invgate-service-desk-mcp\n\n[![CI](https://github.com/tracegazer/invgate-service-desk-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/tracegazer/invgate-service-desk-mcp/actions/workflows/ci.yml)\n[![PyPI](https://img.shields.io/pypi/v/invgate-service-desk-mcp)](https://pypi.org/project/invgate-service-desk-mcp/)\n[![Python](https://img.shields.io/pypi/pyversions/invgate-service-desk-mcp)](https://pypi.org/project/invgate-service-desk-mcp/)\n[![License: MIT](https://img.shields.io/pypi/l/invgate-service-desk-mcp)](LICENSE)\n[![MCP Registry](https://img.shields.io/badge/MCP_Registry-published-0a7ea4)](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.tracegazer/invgate-service-desk-mcp)\n[![Smithery](https://smithery.ai/badge/tracegazer/invgate-service-desk-mcp)](https://smithery.ai/servers/tracegazer/invgate-service-desk-mcp)\n\n<!-- mcp-name: io.github.tracegazer/invgate-service-desk-mcp -->\n\n> A [Model Context Protocol](https://modelcontextprotocol.io) server for **InvGate Service Desk / Service Management**.\n\nGive your AI assistant full access to your InvGate Service Desk — query incidents, look up users, search the knowledge base, check assets, and manage tickets — all through natural language.\n\n**96 tools** across 11 domains. Read-only by default, with optional write operations behind explicit opt-in.\n\n## Install in one click\n\nThe easiest way to use this server with **Claude Desktop** (and other MCPB-compatible clients) is the prebuilt bundle:\n\n**➡️ [Download `invgate-service-desk.mcpb`](https://github.com/tracegazer/invgate-service-desk-mcp/releases/latest/download/invgate-service-desk.mcpb)** — then double-click it. Claude Desktop opens the installer, prompts for your InvGate base URL and API token, and you're done. No Python, no `npx`/`uvx`, no config files.\n\nThe `.mcpb` is attached to every [GitHub Release](https://github.com/tracegazer/invgate-service-desk-mcp/releases) and mirrored on [Smithery](https://smithery.ai/). Prefer a package manager or container? See [Quick start](#quick-start) below.\n\n## What can it do?\n\n| Domain | Tools | Examples |\n|--------|------:|---------|\n| **Catalog** | 5 | List priorities, statuses, incident types, categories (with search), sources |\n| **Incidents** | 34 | Get ticket details, list by status/agent/customer, create & update tickets, reassign, comment, manage approvals |\n| **Users & Groups** | 7 | Look up users, find by email/phone, list group members |\n| **Knowledge Base** | 10 | Search articles, browse categories, create & update articles |\n| **Custom Fields** | 9 | List field definitions, get options (list/tree), fields by category |\n| **Organization** | 11 | Helpdesks, levels, locations, company structure |\n| **Assets / CIs** | 6 | Find assets linked to incidents, CI relationships |\n| **Time Tracking** | 4 | View logged hours, log new time entries |\n| **Triggers** | 2 | List automation rules and their executions |\n| **Workflows** | 3 | Inspect workflow fields, processes, and field values |\n| **Breaking News** | 5 | View announcements, statuses, types |\n\n> **63 read-only tools** work out of the box. **33 write tools** (incidents, KB, time tracking) activate only when you explicitly opt in.\n\n## Quick start\n\n### 1. Install\n\n```bash\npip install invgate-service-desk-mcp\n```\n\nOr run without installing (requires [uv](https://docs.astral.sh/uv/)):\n\n```bash\nuvx invgate-service-desk-mcp\n```\n\n### 2. Connect to Claude Desktop\n\nAdd this to your `claude_desktop_config.json`:\n\n```jsonc\n{\n  \"mcpServers\": {\n    \"invgate\": {\n      \"command\": \"uvx\",\n      \"args\": [\"invgate-service-desk-mcp\"],\n      \"env\": {\n        \"INVGATE_BASE_URL\": \"https://acme.sd.cloud.invgate.net\",\n        \"INVGATE_API_TOKEN\": \"your-api-token\"\n      }\n    }\n  }\n}\n```\n\nRestart Claude Desktop. That's it — start asking about your tickets.\n\n<details>\n<summary>Using pip install instead of uvx</summary>\n\n```jsonc\n{\n  \"mcpServers\": {\n    \"invgate\": {\n      \"command\": \"invgate-service-desk-mcp\",\n      \"env\": {\n        \"INVGATE_BASE_URL\": \"https://acme.sd.cloud.invgate.net\",\n        \"INVGATE_API_TOKEN\": \"your-api-token\"\n      }\n    }\n  }\n}\n```\n\n</details>\n\n<details>\n<summary>Enabling write operations</summary>\n\nBy default the server is **read-only**. Opt into writes with `INVGATE_WRITE_PROFILE`:\n\n| Profile          | Reads      | Writes                                                            |\n|------------------|------------|-------------------------------------------------------------------|\n| `none` (default) | everything | nothing                                                           |\n| `support`        | everything | incidents (tickets, comments, reassign, approve) + time tracking  |\n| `full`           | everything | incidents + time tracking + Knowledge Base                        |\n\n```jsonc\n{\n  \"mcpServers\": {\n    \"invgate\": {\n      \"command\": \"uvx\",\n      \"args\": [\"invgate-service-desk-mcp\"],\n      \"env\": {\n        \"INVGATE_BASE_URL\": \"https://acme.sd.cloud.invgate.net\",\n        \"INVGATE_API_TOKEN\": \"your-api-token\",\n        \"INVGATE_WRITE_PROFILE\": \"support\"\n      }\n    }\n  }\n}\n```\n\n> **Compatibility:** the legacy `INVGATE_ENABLE_WRITES=1` still works and maps to `full`.\n> If both are set, the profile wins and a warning is printed to stderr. Note: `support`\n> deliberately keeps the Knowledge Base read-only. An invalid profile name fails fast at startup.\n\n> **Warning:** write mode lets the connected agent create, modify, and delete real content through your InvGate credential. There is no API to delete a ticket — created tickets can only be cancelled, not removed.\n\n</details>\n\n### 3. Get your API token\n\nIn your InvGate Service Desk instance: **Settings > Integrations > API** (or ask your admin). The server authenticates via HTTP Basic with username `api` and your token as the password.\n\n## Configuration\n\nConfiguration resolves in this order (highest priority first):\n\n1. **Environment variables** (always win)\n2. **TOML config** at `~/.config/invgate-service-desk-mcp/config.toml`\n\n| Env var | TOML key | Description |\n|---------|----------|-------------|\n| `INVGATE_BASE_URL` | `base_url` | Instance URL, e.g. `https://acme.sd.cloud.invgate.net` |\n| `INVGATE_API_TOKEN` | `api_token` | API token (HTTP Basic password) |\n| `INVGATE_API_USERNAME` | `api_username` | HTTP Basic username (optional, defaults to `api`) |\n| `INVGATE_WRITE_PROFILE` | `write_profile` | Write access profile: `none` (default), `support`, or `full` |\n| `INVGATE_TELEMETRY` | `telemetry_enabled` | Enable OpenTelemetry (default: `false`) |\n| `INVGATE_TELEMETRY_DETAIL` | `telemetry_detail` | Span detail: `metadata` (default), `ids`, or `full` |\n\n```toml\n# ~/.config/invgate-service-desk-mcp/config.toml\nbase_url = \"https://acme.sd.cloud.invgate.net\"\napi_token = \"...\"\n# api_username = \"api\"\n# write_profile = \"none\"  # \"none\" (default) | \"support\" | \"full\"\n# telemetry_enabled = false\n# telemetry_detail = \"metadata\"\n```\n\n> **Tip:** create the config directory first: `mkdir -p ~/.config/invgate-service-desk-mcp`\n\nSee [`config.toml.example`](config.toml.example) for a copy-paste template.\n\n## Running the server\n\n```bash\ninvgate-service-desk-mcp                 # STDIO transport (default)\ninvgate-service-desk-mcp --transport sse # SSE/HTTP transport\n```\n\n> **Security note:** STDIO (the default) keeps everything local. The `sse` and `streamable-http` transports have no built-in authentication — only use them bound to loopback or behind an authenticated reverse proxy.\n\n## Observability (optional)\n\nThe server can emit OpenTelemetry traces, metrics, and logs — completely opt-in and vendor-neutral. Export to any OTLP-compatible backend (Dynatrace, Grafana, Datadog, Jaeger, etc.).\n\n```bash\npip install \"invgate-service-desk-mcp[telemetry]\"\n\nexport INVGATE_TELEMETRY=1\n```\n\nOTLP endpoint and headers are configured via standard OpenTelemetry env vars (not in the TOML file):\n\n<details>\n<summary>Dynatrace setup</summary>\n\n```bash\nexport OTEL_EXPORTER_OTLP_ENDPOINT=\"https://<your-env>.live.dynatrace.com/api/v2/otlp\"\nexport OTEL_EXPORTER_OTLP_HEADERS=\"Authorization=Api-Token <YOUR_DT_TOKEN>\"\nexport OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE=delta\nexport OTEL_SERVICE_NAME=invgate-service-desk-mcp\n```\n\nToken scopes needed: `openTelemetryTrace.ingest`, `metrics.ingest`, `logs.ingest`.\nSee [`docs/observability-dynatrace.md`](docs/observability-dynatrace.md) for a detailed guide.\n\n</details>\n\n<details>\n<summary>Generic OTLP collector</summary>\n\n```bash\nexport OTEL_EXPORTER_OTLP_ENDPOINT=\"http://localhost:4318\"\nexport OTEL_SERVICE_NAME=invgate-service-desk-mcp\n```\n\n</details>\n\n**Signals emitted:**\n\n- **Traces** — tool execution spans (GenAI semantic conventions) + InvGate API request spans with response size and item count\n- **Metrics** — `mcp.tool.duration`, `invgate.client.request.duration`, `mcp.tool.errors`, `invgate.response.item_count`, `invgate.response.size`\n- **Logs** — tool errors and unexpected API response shapes, correlated to traces (OTLP only, never stdout)\n\n## Development\n\n```bash\ngit clone https://github.com/tracegazer/invgate-service-desk-mcp.git\ncd invgate-service-desk-mcp\nuv venv && uv pip install -e \".[dev]\"\npytest\n```\n\n## License\n\n[MIT](LICENSE)\n",
  "bytes": 9216,
  "sha": "f83a7fabf2944cddcd1d5bc75fcfbf2ac3a339fd2eca025eadbcb31fce765884",
  "repo_slug": "tracegazer/invgate-service-desk-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_tracegazer_invgate_service_des_a9935dcc/readme"
}