itglue-mcp

Read-only MCP server over the Example Corp / examplecorp IT Glue tenant (your-company.itglue.com). Answers "what do we know about this customer" from chat, and answers "what are the credentials for X" with an IT Glue link rather than a secret.

Built on the house remote-MCP standard: fastmcp resource server + Entra ID auth, behind Nginx Proxy Manager on Portainer. See ~/.claude/context/mcp-server-playbook.md.

Findings from the API and content audit that shaped this design are in FEASIBILITY.md. Read §0 and §1 before changing anything.

The two guarantees

1. Nothing is ever written to IT Glue

The API key in use has full write and delete rights. Verified, not assumed:

PATCH  /configurations/999999999  -> 404 "Record not found"
PATCH  /passwords/999999999       -> 404 "Record not found"
DELETE /configurations/999999999  -> 404

A key without write permission fails 401/403 before the record lookup. A 404 means the mutation was authorized and merely had nothing to act on. IT Glue does not issue read-scoped classic API keys, so there is no server-side permission to lean on — the guarantee is entirely in this codebase:

• client.py exposes exactly one request method, get(), which hardcodes method="GET".

• No post/patch/put/delete helper exists. Adding one is a security regression, not a feature.

• A WriteAttemptError tripwire fires if a non-GET is ever constructed.

• tests/smoke_local.py asserts both the absent methods and the absent verbs.

If write-back is ever built (FEASIBILITY.md Option C), it goes in a separate process with a separate key. That separation is the whole safety argument, because IT Glue documents are customer-authored text that a model summarises — i.e. untrusted input.

2. No credential value is ever returned

itglue_find_credential returns a pointer: the credential's name, category, which device it belongs to, when it last rotated, whether OTP is on, and an IT Glue deep link. The human clicks the link and signs in to IT Glue to reveal the secret.

Redaction happens on the way into the mirror (redact.py), so no downstream tool can leak a field by forgetting to strip it. Records IT Glue marks restricted are dropped entirely.

Related MCP server: invgate-mcp

Why there's a local mirror

IT Glue's filter[name] is exact-match only, and some filters are silently ignored rather than rejected:

So server-side search either needs the exact string the model doesn't have, or quietly lies. Everything is therefore mirrored into RAM and searched locally (search.py, index.py).

Sync cost, measured: ~10 requests for ~7,000 structured records; ~400 requests for 300 document bodies (95 org listings + per-doc fetches), against a ceiling of 3,000 per 5 minutes. Core warms in seconds; documents warm in the background over a few minutes, and document tools report status: indexing instead of hanging.

Nothing is persisted to disk — the corpus is small, so a restart just re-syncs and there's no stale-cache failure mode.

Search is deliberately forgiving because real queries look like "EF Vista Del Mar Unified Controller": an acronym, a full name, and a product spelled Unifi in the data. Handled by acronym matching (EF → Example Foundation), per-word fuzzy matching (unified ≈ unifi, ratio 0.83), org-token subtraction, and atomic identifier handling so 192.0.2.51 isn't shredded into ['10','105','251'].

Tools

All are annotated readOnlyHint: true.

The query this was built for

"What are the credentials for the Example Foundation UniFi controller?"

itglue_find_credential infers the org from the sentence, subtracts its name words, fuzzy-matches unified→unifi across 460 EF credential records, and returns five pointers — the two on the current Unifi Controller (New Staging) and the three older VDM_Cloudwifi logins — each with a clickable link, the device URL, and the last-rotated date. No secret leaves the server.

Local development

python -m venv .venv && .venv/Scripts/activate    # Windows
pip install -r requirements.txt
cp .env.example .env      # fill in ITGLUE_API_KEY; set MCP_AUTH_ENABLED=false
python -m itglue_mcp

Never expose an auth-off server. MCP_AUTH_ENABLED=false is for MCP Inspector on localhost only.

Smoke test (live, read-only)

python tests/smoke_local.py

47 assertions against the live tenant. Reads ~/.claude/credentials/itglue.env if ITGLUE_API_KEY isn't set in the environment, and needs no fastmcp install. The credential assertions are the important ones — if any fail, stop and fix before deploying.

Deploy

1. Entra app + group + token lifetime — scripts/setup_entra_app.ps1 (dry-run by default; -Apply to execute). Provisions the app, the ITGlue-MCP-Users security group with the five initial members, assignment enforcement, and a 23h59m access-token lifetime policy. See docs/ENTRA_SETUP_CHECKLIST.md.

2. Portainer stack + NPM — PORTAINER_DEPLOY.md. Host port 8111 (probed free on 10.0.0.10, 2026-07-29 — 8100 and 8110 are in use). Public host itglue-mcp.example.com.

Housekeeping

• Rotate the IT Glue key — still outstanding. It now lives at ~/.claude/credentials/itglue.env in house KEY=VALUE format (migrated 2026-07-30 from a plaintext .itglueapicreds.txt), but that was a format change, not a rotation — the key value is unchanged. It has write + delete rights and sat in a plaintext .txt for an unknown period. To rotate: mint a new key in IT Glue → Account → Settings → API Keys, update itglue.env and the Portainer stack's ITGLUE_API_KEY, then revoke the old one.

• IT Glue auto-revokes API keys unused for 90+ days. The mirror refresh keeps this one warm; if the server is ever parked, expect a 401 on wake.

• Add and remove access via the ITGlue-MCP-Users group, not the code.