sn-mcp

A Model Context Protocol server that lets an LLM talk to a ServiceNow instance — query records, and (only when you turn it on) write them — without handing the model the keys to the kingdom.

Built for a healthcare context. The bar is: a CISO can read this page and know what the model can and cannot touch.

---

The problem

LLMs are useful against ServiceNow. They are also one bad prompt away from reading sys_user, dumping a table, or following instructions hidden in a work note.

Most MCP wrappers solve “can the model call the API?” They skip “what happens when it tries something it shouldn’t?”

Why this exists

The day job is regulated healthcare. I needed an agent that could look at a live instance while I was building — and I would not point a raw API token at that instance.

So the product is not “nine ServiceNow tools.” The product is the safety kernel those tools cannot bypass.

---

How a call works

LLM
  │  stdio (no network, no ports)
  ▼
sn-mcp
  │  1. Zod validation
  │  2. Table + field allowlist      ← default deny
  │  3. Query denylist               ← no identity enumeration
  │  4. HTTPS to ServiceNow (10s cap)
  │  5. Error sanitization           ← LLM never sees stack traces
  │  6. PHI redaction
  │  7. Response wrapper             ← retrieved data is untrusted input
  │  8. Audit log + rate limit
  ▼
ServiceNow

Read tools always go through that path. Write tools add one more gate: BUILDER_MODE is off unless you set it. Idle sessions cannot create, update, delete, or run scripts.

---

Design decisions

These are the ones a stranger needs. The rest, including what was rejected, live in DECISIONS.md.

Decision	Choice	Why
Default deny	Only listed tables and fields come back	A miss is a closed door, not an open one
Writes are opt-in	BUILDER_MODE=true or the write tools refuse	An idle chat cannot change the instance
Errors fail safe	Unknown error category = no hint to the model	Better a confused model than a leaked schema
PHI regex is not the primary control	Allowlist is primary; redaction is defense in depth	Regex will miss things. We say that out loud.
Retrieved data is untrusted	Every SN payload is wrapped and tagged	Stops a work note from becoming an instruction
Identity fields are denied everywhere	One SYSTEM_IDENTITY_FIELDS list, every table	Closing caller_id and leaving sys_created_by is not a lock

What this is not: a production connector for a hospital instance. It is built and tested against a developer instance, with Basic auth. OAuth is the gating requirement before it ever sees real PHI.

---

What it can do

Always on (still subject to the kernel):

Tool	Purpose
query_table	Query an allowlisted table
get_record	Fetch one record by sys_id
search_kb	Search published knowledge articles
count_table	Return a count — no rows cross the boundary
health_check	Is ServiceNow up, and can we write the audit log?

Off until you opt in:

Tool	Purpose
create_record / update_record / delete_record	Write to the instance
execute_script	Run server-side JavaScript. Treat it as admin.

Default allowlist: incident, change_request, problem, sc_request, sc_task, kb_knowledge, alm_hardware, wm_order. Clinical tables, users, scripts, attachments, and email are denied by name.

---

Run it

git clone https://github.com/dadshorts/sn-mcp.git
cd sn-mcp
npm install
cp .env.example .env   # set SN_INSTANCE, SN_USERNAME, SN_PASSWORD
npm test               # regression suite against the safety kernel
node src/index.mjs     # listens on stdio

Point your MCP client at node src/index.mjs. Credentials stay in .env (gitignored). Leave BUILDER_MODE unset unless you are sitting down to write.

---

What's verified

• Safety kernel + write gate exercised on a live developer instance
• Regression suite for allowlist, denylist, wrapping, PHI false-positives, and builder-mode refusals
• Audit log written for every tool call, including refusals
• Months of local operation while building ServiceNow work

This repo is the server. It does not include instance credentials, audit logs, or production data.