mcp-itglue

An MCP (Model Context Protocol) server for the IT Glue API, built for MSPs that want AI assistants to read — and safely write — their documentation.

• Documents & sections — list, read, create, update, publish, delete
• Flexible assets — browse asset types and their fields, list/read/create/update/delete assets
• Attachments & images — attach an image/file to any record from base64, a URL, or a local path; list and delete attachments
• Semantic vector search — "how do I remove a backup agent" finds the Veeam decommissioning runbook, even when the words don't match (OpenAI or Azure OpenAI embeddings, local JSON index)
• Role-based access control — viewer / editor / admin bearer tokens decide which tools each session can even see
• Bring your own key — clients may supply their own IT Glue API key per session, so IT Glue's own permissions apply
• Index freshness — IT Glue webhook, post-write self-refresh, and a manual refresh endpoint
• Transports — stdio for local use, streamable HTTP for shared deployments; Docker image included

Installation

You need an IT Glue API key (IT Glue → Account → Settings → API Keys). Non-US accounts set ITGLUE_REGION to eu or au.

npx (recommended)

Claude Desktop (claude_desktop_config.json) or Claude Code (.mcp.json):

{
  "mcpServers": {
    "itglue": {
      "command": "npx",
      "args": ["-y", "mcp-itglue"],
      "env": { "ITGLUE_API_KEY": "ITG.xxxx" }
    }
  }
}

Claude Code one-liner:

claude mcp add itglue --env ITGLUE_API_KEY=ITG.xxxx -- npx -y mcp-itglue

Claude Desktop users can instead grab mcp-itglue.mcpb from the latest release — open it with Claude Desktop and fill in the API key when prompted.

stdio always runs with the full tool surface — it is a local, single-user transport using your own key.

Docker

The container image defaults to the HTTP transport (for shared deployments):

docker run --rm -p 3000:3000 \
  -e ITGLUE_API_KEY=ITG.xxxx \
  ghcr.io/mspstack/mcp-itglue

For local stdio use under Docker:

{
  "mcpServers": {
    "itglue": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "ITGLUE_API_KEY", "ghcr.io/mspstack/mcp-itglue", "--transport", "stdio"],
      "env": { "ITGLUE_API_KEY": "ITG.xxxx" }
    }
  }
}

From source

git clone https://github.com/mspstack/mcp-itglue.git && cd mcp-itglue
npm install && npm run build
ITGLUE_API_KEY=ITG.xxxx node dist/index.js

HTTP deployment

ITGLUE_API_KEY=ITG.xxxx \
MCP_TOKENS_VIEWER="alice:$(openssl rand -hex 32)" \
MCP_TOKENS_EDITOR="automation:$(openssl rand -hex 32)" \
MCP_TOKENS_ADMIN="ops:$(openssl rand -hex 32)" \
npx -y mcp-itglue --transport http --port 3000

Or with Docker:

docker run --rm -p 3000:3000 \
  -e ITGLUE_API_KEY -e MCP_TOKENS_VIEWER -e MCP_TOKENS_EDITOR -e MCP_TOKENS_ADMIN \
  ghcr.io/mspstack/mcp-itglue

Endpoints:

| Route | Purpose | |---|---| | POST/GET/DELETE /mcp | MCP streamable-http endpoint | | GET /health | Liveness probe | | POST /webhook/itglue | IT Glue webhook → incremental index update | | POST /index/refresh | Manual index refresh (shared secret or admin token) |

Sessions are held in memory — run a single instance (or add sticky sessions) behind your load balancer.

Access control

Role tokens

Three env vars hold comma-separated label:token lists:

MCP_TOKENS_VIEWER="alice:tokA,bob:tokB"   # read-only tools
MCP_TOKENS_EDITOR="hatz:tokC"             # + create/update/publish, delete section
MCP_TOKENS_ADMIN="ops:tokD"               # + delete documents / flexible assets

Clients authenticate with Authorization: Bearer <token>. The label appears in the audit log ([rbac] session … for alice (viewer)) and lets you revoke one person's token without rotating everyone's.

Tools a role cannot use are not registered for that session — a viewer doesn't even see itglue_create_document in tools/list — and a runtime guard re-checks the role on every call as defense in depth. Session ids never carry privilege: every request re-authenticates, and presenting a different principal against an existing session returns 403.

If no tokens are configured, the server runs in dev mode: all requests get admin access and a loud startup warning. Don't do this in production.

Bring your own IT Glue key (BYOK)

Clients may send their own IT Glue API key in the x-itglue-api-key header on the initialize request. The session then talks to IT Glue with that key and gets the full tool surface — IT Glue's own key permissions are the effective access control. CLIENT_ITGLUE_KEYS controls the policy:

| Value | Behavior | |---|---| | with-token (default) | BYOK allowed, but a valid bearer token is still required — protects your server from being an open proxy | | open | An IT Glue key alone authenticates (trusted networks / local use) | | disabled | The header is rejected; only the server-wide key is used |

With BYOK enabled the server-wide ITGLUE_API_KEY becomes optional: sessions without a client key are rejected with a clear error. Client keys are never logged; sessions are bound to a SHA-256 hash of the key and audit-labeled byok:<hash-prefix>.

Tools

| Tool | Tier | |---|---| | itglue_list_organizations, itglue_get_organization | read | | itglue_list_documents, itglue_get_document | read | | itglue_list_document_folders | read | | itglue_list_document_sections, itglue_get_document_section | read | | itglue_list_flexible_asset_types, itglue_get_flexible_asset_type | read | | itglue_list_flexible_assets, itglue_get_flexible_asset | read | | itglue_list_attachments | read | | itglue_vector_search, itglue_vector_index_status | read | | itglue_create_document, itglue_update_document, itglue_publish_document | write | | itglue_create_document_section, itglue_update_document_section | write | | itglue_delete_document_section † | write | | itglue_create_flexible_asset, itglue_update_flexible_asset | write | | itglue_create_attachment | write | | itglue_build_vector_index | write | | itglue_delete_documents | destructive | | itglue_delete_flexible_asset | destructive | | itglue_delete_attachment | destructive | | itglue_find_endpoint, itglue_get ‡ | read |

Viewer = read. Editor = read + write. Admin = everything. † Permanent, but editor-tier: editors need it to restructure documents and can already blank section content via update. ‡ Advanced toolset (opt-in, off by default): itglue_get is a read-only GET passthrough for any API path the curated tools don't wrap, and itglue_find_endpoint searches a curated endpoint catalog. Enable with ITGLUE_ADVANCED_TOOLSET=true or --advanced. Password resources (/passwords) are hard-blocked — credential values never reach the model.

Vector tools appear only when an embedding provider is configured.

Vector search

Set OPENAI_API_KEY (or AZURE_OPENAI_API_KEY + AZURE_OPENAI_ENDPOINT, where EMBEDDING_MODEL is your deployment name), then run itglue_build_vector_index per organization. The index is a JSON file at VECTOR_INDEX_PATH (default ./vector-index.json) — on ephemeral hosts, point it at a persistent volume.

The index stays fresh three ways:

1. IT Glue webhook — in IT Glue, webhooks are sent by Workflows (Admin → Workflows): add a Document trigger (created/updated) with a Webhook action. Workflow actions cannot send custom headers, so put the shared secret in the URL:

   https://<host>/webhook/itglue?secret=<ITGLUE_WEBHOOK_SECRET>

   and use a JSON payload template like:

   | Key | Value | |---|---| | event | [trigger_name] | | resource_url | [resource_url] | | resource_name | [resource_name] | | organization_name | [organization_name] |

   The document id is parsed from resource_url; the trigger name maps to created/updated/deleted by keyword. Classic JSON:API-style payloads with an x-itglue-webhook-signature HMAC-SHA256 header are also accepted.

2. Self-refresh — documents created/updated/published/deleted through this server's tools are re-indexed automatically in the background.

3. Manual refresh — POST /index/refresh with Authorization: Bearer <ITGLUE_WEBHOOK_SECRET> (or an x-refresh-secret header, or an admin token). Body {"document_id": "123"} refreshes one document; an empty body re-crawls every indexed organization. Returns 202 and processes in the background.

Configuration reference

| Variable | Default | Purpose | |---|---|---| | ITGLUE_API_KEY | — | Server-wide IT Glue API key | | ITGLUE_REGION | us | us, eu, or au | | ITGLUE_BASE_URL | per region | Override the API base URL | | TRANSPORT | stdio | stdio or http | | PORT | 3000 | HTTP port | | MCP_TOKENS_VIEWER/EDITOR/ADMIN | — | label:token,label:token per role | | CLIENT_ITGLUE_KEYS | with-token | BYOK policy: disabled, with-token, open | | ALLOWED_ORIGINS | — | Extra browser origins allowed on /mcp (comma-separated). Requests without an Origin header and localhost origins always pass; other browser origins are rejected with 403 | | ITGLUE_ADVANCED_TOOLSET | false | true/1 registers the advanced toolset (itglue_get, itglue_find_endpoint) | | ITGLUE_WEBHOOK_SECRET | — | Webhook signature + /index/refresh secret | | VECTOR_INDEX_PATH | ./vector-index.json | Vector index file | | OPENAI_API_KEY | — | Enables vector search (OpenAI) | | AZURE_OPENAI_API_KEY / AZURE_OPENAI_ENDPOINT / AZURE_OPENAI_API_VERSION | — | Enables vector search (Azure OpenAI) | | EMBEDDING_MODEL | text-embedding-3-small | Embedding model / Azure deployment |

CLI flags --transport, --port, --region, --base-url, --advanced override the environment. Run mcp-itglue --help for details.

Notes & limits

• IT Glue rate limit: 3000 requests / 5 minutes per key.
• The IT Glue documents API is only partially documented; document/section endpoints follow observed API behavior.
• Flexible-asset trait updates replace the whole traits object — the update tool's description warns the model to send all traits back.
• List tools return summary fields per item (in both text and structuredContent) so default page sizes stay within client token limits; the itglue_get_* tools return the complete record.
• IT Glue has no user impersonation: a given API key always acts as itself. RBAC here controls what tool calls a session may make; BYOK delegates to IT Glue's own key permissions.

Development

npm install
npm run dev          # stdio via tsx
npm run dev:http     # http via tsx
npm test             # vitest
npm run build        # tsc → dist/

Author

Built by Eugene Samotija (@selic) — defency.net. More projects: github.com/selic · LinkedIn

License

MIT