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
• Images inside documents — upload a picture into a document (inline in a Text/Step section, or into a Gallery) from base64, a URL, or a local path, and embed it with the returned <img src>; get and delete document images
• Attachments — attach any file to a record's Attachments panel (documents, flexible assets, configurations, …); 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:

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:

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

Viewer = read. Editor = read + write. Admin = everything. † Permanent, but editor-tier: editors need these to restructure documents and can already blank section content (or edit an <img> out of it) via update.

Images in documents vs. attachments

IT Glue has two unrelated upload paths. Attachments (itglue_create_attachment) land in a record's Attachments side panel and never render in a document's body. To show a picture inside a document, use itglue_create_document_image:

1. Upload with document_id (inline) or document_id + gallery_id (the document_gallery_id of a Gallery/Step section).
2. For inline images, put the returned inline_resource_url verbatim into the section HTML: <img src="https://raw.githubusercontent.com/mspstack/mcp-itglue/main/6255696/docs/17772862/images/27211966"> — or pass append_to_section_id and the tool appends it to an existing Text/Step section for you.

IT Glue strips data: URIs and its own S3 URLs from section content; only these relative paths (and public https:// links) survive.

Getting a file from the client to the server (staged uploads)

Tool arguments travel through the model, so content_base64 only works for tiny files — a screenshot is megabytes of base64 the model would have to reproduce token by token (and IT Glue rejects the truncated result with NotIdentifiedByImageMagickError). Over HTTP the server therefore offers staged uploads:

1. The model calls itglue_request_upload (file_name optional) and gets an upload_id, a URL, and a ready-to-run curl.
2. The client PUTs the file to that URL from a shell.
3. The model calls itglue_create_document_image or itglue_create_attachment with upload_id.

Slots live 15 minutes, are bound to the requesting principal (token label / BYOK key), and are consumed once. Two backends, chosen with UPLOAD_STAGING:

url remains the simplest source for anything already hosted on the web. ‡ 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:

   Copy

   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

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