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.

Field	Returned?	Why
password	Never	Not configurable. IT Glue also refuses this key a value (?show_password=true → 401).
notes	Never	Not configurable. In this tenant, 15 of 25 sampled records had notes, and password notes are where PINs and recovery codes live.
otp_secret, autofill_selectors	Never	TOTP seed / selector material.
username	Off by default	Half a credential. ITGLUE_INCLUDE_USERNAME=true to enable.
resource_url	Yes	This is the deliverable.

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.

---

Why there's a local mirror

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

Query	Result
filter[name]=Example Corp	1
filter[name]=Info	0
filter[name]=nfoN	0
/contacts?filter[name]=john	all 318 contacts (filter ignored)

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

Tool	What it does
itglue_find_organization	Resolve a name/acronym/fragment to organizations. Use first when ambiguous.
itglue_find_credential	Which credentials exist for a device/service + IT Glue links. Never a value.
itglue_search_documents	Full-text search across document bodies. Returns snippet + last-updated date + link.
itglue_get_document	One document's full text, HTML → plain text.
itglue_find_configuration	Device by name, hostname, IP, serial or MAC. Searches configurations and flexible assets.
itglue_organization_brief	Whole customer in one call: sites, contacts, device counts, documents, domains, expirations.
itglue_list_locations	Street addresses, postal codes, phones. The cleanest data in the tenant (79% complete).
itglue_list_contacts	Emails, phones, titles; important_only filter.
itglue_expirations	Warranties, SSL, domains — expiring or overdue.
itglue_documentation_health	Gap report, worst-first: missing fields, no site address, no Technical Overview Sheet, credentials unrotated 3+ years.
itglue_health_check	Connectivity, mirror freshness, safety posture. Run this first when something looks off.

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.