How do I install Servicenow MCP Ai?

Copy the http config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Servicenow MCP Ai need an API key?

The publisher lists these environment variables: SN_INSTANCE, SN_USER, SN_PASSWORD, SN_AUTH, SN_API_KEY, SN_TOOL_PACKAGES.

What transport does Servicenow MCP Ai use?

Servicenow MCP Ai is reached over HTTP.

When was Servicenow MCP Ai last checked?

Last checked 2026-11-09. ServiceNow MCP server — 100 tools over the full REST surface, every auth method, flows, diagrams.

Servicenow MCP Ai MCP server

servicenow-mcp-ai — ServiceNow MCP Server

📖 Documentation site →

A Model Context Protocol server that lets an MCP client (VS Code, Claude Desktop, etc.) run commands against a ServiceNow instance through its REST APIs — Table, Aggregate, Attachment, Import Set, Batch and CMDB, plus the Service Catalog, Change Management and Knowledge plugin APIs. Credentials are kept in a local env file and can be updated at runtime through a tool.

Upgrading from 2.x? 3.0 has breaking defaults (plan tokens for destructive applies, protected system tables, a smaller default tool set). Run npx servicenow-mcp-ai migrate --write once: it carries your env file and MCP client config over and adds SN_COMPAT=2, which keeps every 2.x default you have not set. See the CHANGELOG → "Migration at a glance" for each change.

Upgrading from 1.x? v2.0 makes writes plan-by-default: create/update/delete and the other record-write tools return a non-mutating preview unless you pass apply: true (or set SN_WRITE_MODE=apply to restore the v1 "execute immediately" behaviour). See the CHANGELOG → 2.0.0 for the full migration note.

Contents: Quick demo · Features · Requirements · Setup · Configure credentials · Run / debug · Develop · Tools · Resources · Prompts · Project structure · Security notes · Project documentation · Support

Built and maintained in my own time — if it helps, a GitHub Sponsors tip keeps it going. Full Support options are near the end.

Quick demo

Three things the platform makes hard, one call each. Point your MCP client at an instance (Setup) and ask:

1. "Where is this field actually used?" — every script, business rule, client script, UI policy/action and ACL that touches it, as JSON or a Mermaid graph. The IDE-grade find usages ServiceNow has no button for:

// servicenow_where_used
{
  "kind": "field", // "table" | "field" | "script"
  "name": "u_cost_center",
  "mermaid": true, // also render a reference graph
}

2. "What runs when I save this record?" — the full automation chain in execution order (display → before → after → async business rules, then flows, workflows and notifications), each with its condition — a logical test that runs nothing:

// servicenow_trace_table_event
{
  "table": "incident",
  "operation": "update", // insert | update | delete | query
}

3. "What drifted between dev and prod?" — a Markdown diff of tables, columns, scripts (matched by sys_id then name, with a unified diff of every changed script) and plugins between two configured profiles — plus, on request, properties, choices, ACLs, notifications, flows, catalog items and roles — with a CI-friendly exit code so a pipeline can block a risky deploy:

servicenow-mcp-ai drift dev prod   # report on stdout; exit 1 on drift, 0 if clean

All three are read-only and work against any instance — including a free PDI — with the model and client of your choice.

Features

Full Table API: query, read, create, update and delete records on any table, with encoded queries, field selection and pagination.
Extra ServiceNow APIs: Aggregate (Stats), Attachment (list/upload/download/delete), Import Set, Batch (many REST calls in a single request), plus table/column metadata (sys_db_object, sys_dictionary).
Process & plugin APIs: CMDB (class-aware CI CRUD + meta, relationship reads from cmdb_rel_ci, IRE identify-and-reconcile with an identify-only plan), Service Catalog (browse/order items), Change Management (typed creation + conflict detection) and Knowledge (article search). Plugin-scoped APIs report clearly when not active on the instance.
Script intelligence: read and search the instance's own code (business rules, script includes, client scripts, UI policies/actions, scheduled jobs, transform/REST scripts, ACLs, Service Portal widgets, UI pages/scripts/macros, processors, email/fix/ validation scripts, script actions, data sources, REST message functions, transform maps/entries, catalog client scripts and dictionary calculations / defaults) and get a table's full automation picture — all read-only over the Table API. servicenow_search_code returns every matching line per artefact (up to 20, with a line of context either side) and, like servicenow_where_used, takes an optional application scope. servicenow_where_used also finds structural references — dictionary reference fields, list and form layouts, catalog variables, flow inputs and reports — in a separate structural section.
Flow tracing & code checking (Phase 8): deterministically trace what a table operation runs (flows package — business rules, flows, workflows and notifications, in order, with a Mermaid flowchart), read Flow Designer flows and run history, explain Process Automation Designer playbooks (servicenow_explain_flow with kind: "playbook" — lanes as Mermaid subgraphs, activities, triggers, variants), and lint scripts against a local rule set with an aggregate code-health report (codecheck; domains: true adds the flow, Service Portal and legacy-workflow analysers). Run ATF tests via the CI/CD API (atf, opt-in, non-default — the run tools execute on the instance).
Journal-based undo (revert): list the local write journal and revert one applied create/update/delete — with a drift check against later edits.

Requirements

Node.js 22.12+ (enforced: engines + a runtime guard with a clear message; the project targets the version in .nvmrc).

Setup

From source (for development):

npm install
npm run build

Or run the published package directly, without cloning:

npx servicenow-mcp-ai

Install in your MCP client

Every client launches the same stdio command, npx -y servicenow-mcp-ai (Node.js 22.12+), under the server name servicenow. The one-click links and snippets below carry no credentials: keep them in the env file (~/.config/servicenow-mcp-ai/.env, see Configure credentials), run the one-time npx servicenow-mcp-ai login for OAuth, or ask the assistant to call servicenow_set_credentials once the server is connected. A real environment variable set in a client config overrides the env file, so only add an env block when you mean it — and never put SN_PASSWORD or other secrets into a client config you share or commit (see SECURITY.md).

Client	One line	Config file
VS Code (Copilot Chat)	Button above, or `code --add-mcp` (below) — or the ServiceNow MCP extension	`.vscode/mcp.json` (`servers`)
VS Code Insiders	Button above, or `code-insiders --add-mcp` (below)	`.vscode/mcp.json` (`servers`)
Claude Code	`claude mcp add servicenow -- npx -y servicenow-mcp-ai`, or the plugin	`.mcp.json` (`mcpServers`)
Claude Desktop	— (edit the config file)	`claude_desktop_config.json` (`mcpServers`)
Cursor	Button above, or the `cursor://` deeplink (below)	`~/.cursor/mcp.json` or `.cursor/mcp.json` (`mcpServers`)
Windsurf	— (edit the config file)	`~/.codeium/windsurf/mcp_config.json` (`mcpServers`)
Cline	— (MCP Servers → Configure MCP Servers)	`cline_mcp_settings.json` (`mcpServers`)
Zed	— (edit settings)	`settings.json` (`context_servers`)
JetBrains AI Assistant	— (Settings → Tools → AI Assistant → Model Context Protocol)	JSON dialog (`mcpServers`)
Gemini CLI	— (edit settings)	`~/.gemini/settings.json` (`mcpServers`)
Codex CLI	`codex mcp add servicenow -- npx -y servicenow-mcp-ai`	`~/.codex/config.toml` (`[mcp_servers.servicenow]`)

The zero-config route is the ServiceNow MCP extension from the Marketplace (code --install-extension ivanbbaev.servicenow-mcp-ai); it registers the server in Copilot Chat (agent mode) automatically, no mcp.json. Source: extension/.

Without the extension, add the server from a terminal (user profile):

code --add-mcp '{"name":"servicenow","command":"npx","args":["-y","servicenow-mcp-ai"]}'
code-insiders --add-mcp '{"name":"servicenow","command":"npx","args":["-y","servicenow-mcp-ai"]}'

The raw deeplinks behind the buttons (paste into a browser address bar):

vscode:mcp/install?%7B%22name%22%3A%22servicenow%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22servicenow-mcp-ai%22%5D%7D
vscode-insiders:mcp/install?%7B%22name%22%3A%22servicenow%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22servicenow-mcp-ai%22%5D%7D

Or a workspace file, .vscode/mcp.json:

{
  "servers": {
    "servicenow": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "servicenow-mcp-ai"]
    }
  }
}

Plugin (zero-config — installs the server wired up):

/plugin marketplace add IvanBBaev/servicenow-mcp-ai
/plugin install servicenow-mcp-ai

The plugin also ships eight workflow skills, two read-only subagents and three hooks — see Plugin skills.

CLI — --scope user makes it available in every project; --env sets a non-secret variable (the instance host) and leaves the secrets in the env file. A value set this way wins over the env file, so drop --env if you switch instances with servicenow_set_credentials:

claude mcp add servicenow --scope user --env SN_INSTANCE=your-instance.service-now.com -- npx -y servicenow-mcp-ai

claude_desktop_config.json — macOS ~/Library/Application Support/Claude/, Windows %APPDATA%\Claude\ (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "servicenow": {
      "command": "npx",
      "args": ["-y", "servicenow-mcp-ai"]
    }
  }
}

Restart Claude Desktop after saving.

Use the button above, or open the deeplink directly:

cursor://anysphere.cursor-deeplink/mcp/install?name=servicenow&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsInNlcnZpY2Vub3ctbWNwLWFpIl19

Or edit ~/.cursor/mcp.json (global) / .cursor/mcp.json (project) with the same mcpServers block as Claude Desktop.

All three take the Claude Desktop mcpServers block unchanged:

Windsurf — ~/.codeium/windsurf/mcp_config.json (Cascade → MCP servers → View raw config), then refresh the server list.
Cline — MCP Servers icon → Configure MCP Servers opens cline_mcp_settings.json.
JetBrains AI Assistant — Settings → Tools → AI Assistant → Model Context Protocol (MCP) → Add → As JSON, paste the block.

{
  "mcpServers": {
    "servicenow": {
      "command": "npx",
      "args": ["-y", "servicenow-mcp-ai"]
    }
  }
}

In Zed's settings.json (Zed → Settings → Open Settings):

{
  "context_servers": {
    "servicenow": {
      "source": "custom",
      "command": "npx",
      "args": ["-y", "servicenow-mcp-ai"],
      "env": {}
    }
  }
}

~/.gemini/settings.json (user) or .gemini/settings.json (project):

{
  "mcpServers": {
    "servicenow": {
      "command": "npx",
      "args": ["-y", "servicenow-mcp-ai"]
    }
  }
}

Check it with /mcp inside a Gemini CLI session.

codex mcp add servicenow --env SN_INSTANCE=your-instance.service-now.com -- npx -y servicenow-mcp-ai

Or ~/.codex/config.toml:

[mcp_servers.servicenow]
command = "npx"
args = ["-y", "servicenow-mcp-ai"]
# Optional, non-secret only — secrets stay in ~/.config/servicenow-mcp-ai/.env:
# env = { SN_INSTANCE = "your-instance.service-now.com" }

Prefer a global install (npm install -g servicenow-mcp-ai)? Replace "command": "npx", "args": ["-y", "servicenow-mcp-ai"] with "command": "servicenow-mcp-ai" in any snippet. The MCP Inspector works the same way: npx @modelcontextprotocol/inspector npx -y servicenow-mcp-ai.

The one-click links are generated from package.json by scripts/install-links.mjs (node scripts/install-links.mjs prints them); test/install-links.test.js fails if this README or the docs site drift from the generated strings.

Install via MCP bundle (.mcpb)

An MCP bundle is one .mcpb file with the server and its dependencies; Claude Desktop (or any MCPB host) installs it in one click, with no npm / npx. Its form asks for the connection keys (only SN_INSTANCE is required) and SN_TOOL_PACKAGES; secrets are marked sensitive (kept in the OS keychain). An empty field falls back to the env file. Not published yet (O-22) — build it with npm run mcpb:pack (dist/mcpb/; -- --validate runs the official validator).

Docker

The repository ships a multi-stage Dockerfile (distroless Node 22 runtime, non-root uid 65532). The image contains exactly what npm pack publishes plus production dependencies, and starts the HTTP transport on 0.0.0.0:3000 by default. No image is published to a registry yet — build it locally:

docker build -t servicenow-mcp-ai .

# Secrets as files (Docker / Kubernetes secrets), mounted read-only
mkdir -p secrets && printf '%s' 'your-password' > secrets/sn_password
openssl rand -hex 32 > secrets/sn_http_token

docker run --rm -p 127.0.0.1:3000:3000 \
  -e SN_INSTANCE=your-instance.service-now.com -e SN_USER=your.user \
  -e SN_PASSWORD_FILE=/run/secrets/sn_password \
  -e SN_HTTP_TOKEN_FILE=/run/secrets/sn_http_token \
  -v "$PWD/secrets:/run/secrets:ro" -v sn-data:/data \
  servicenow-mcp-ai

SN_HTTP_TOKEN is required for any non-loopback bind. The image binds 0.0.0.0 so the published port works; without a token (or OAuth) the server refuses to start (3.0, B6). SN_HTTP_REQUIRE_TOKEN=0 lets it start with a warning, and then every client that reaches the port drives your instance with the configured credentials. Clients send Authorization: Bearer <token>; terminate TLS in front of the container.
OAuth instead of a shared token (N-17): set SN_HTTP_OAUTH_ISSUER (your OIDC provider) and SN_HTTP_OAUTH_RESOURCE (this server's public URL, e.g. https://mcp.example.com/mcp). Clients discover the issuer from /.well-known/oauth-protected-resource and send its JWT access tokens; the token must name the resource as its audience. Optional: SN_HTTP_OAUTH_SCOPES, SN_HTTP_OAUTH_AUDIENCE, SN_HTTP_OAUTH_JWKS_URI. For an issuer that hands out opaque tokens, set SN_HTTP_OAUTH_INTROSPECTION_URI plus its client id and secret (RFC 7662). By default the instance is still called with the configured service account.
Per-user ServiceNow access (N-17 phase 2): add SN_HTTP_OAUTH_USER_TOKENS=true, a 32-byte SN_HTTP_OAUTH_TOKEN_KEY (base64 or hex, e.g. openssl rand -base64 32) and an OAuth client on the instance (SN_OAUTH_CLIENT_ID / SN_OAUTH_CLIENT_SECRET, refresh tokens enabled) whose redirect URL is /oauth/servicenow/callback on the SN_HTTP_OAUTH_RESOURCE origin. The first call from a user returns a link to the instance's sign-in page (URL elicitation; a 2025 session gets -32042, a client without URL elicitation and a background task get an error carrying the link). After the user signs in, the server checks that the account's sys_user field matches the token's claim (SN_HTTP_OAUTH_USER_MATCH, default email=email), keeps the refresh token AES-256-GCM encrypted in SN_HTTP_OAUTH_TOKEN_STORE, and from then on calls the instance as that user, so ServiceNow ACLs apply per user. A user drops their own links with DELETE /oauth/servicenow/link (their bearer token; answers { unlinked, revoked }); the refresh tokens are also revoked on the instance, best effort. Replicas behind one SN_HTTP_OAUTH_RESOURCE can each complete a link when they share SN_HTTP_OAUTH_TOKEN_KEY and the store. Limit: requests authorized with SN_HTTP_TOKEN still use the shared credential.
/data holds the docs directory () and the env file (); mount a volume there to keep them.

HTTP transport: sessions, probes and shutdown

With SN_TRANSPORT=http every MCP session (one initialize) gets its own server:

Per-session state. Enabled packages, the MCP logging level, list-changed notifications, plan tokens, tasks and write caps belong to the session. Connection pools, OAuth tokens and the schema cache are shared and keyed by profile + host.
servicenow_use_instance is session-scoped over HTTP. It switches the profile of the calling session only; other sessions keep theirs and nothing is written. Pass persist: true to also write SN_ACTIVE_PROFILE to the env file (journaled) — that changes the default for sessions that have not switched. Over stdio the switch lasts until the process exits; persist: true writes it there too (3.0, B12).
Lifetime. A session ends on DELETE or after SN_HTTP_SESSION_TTL_SEC idle (default 30 min); a request with an ended session id gets 404 and the client re-initializes. At most SN_HTTP_MAX_SESSIONS (64) are open at once.
DNS-rebinding protection. The Host header must match SN_HTTP_ALLOWED_HOSTS (default: the loopback names on a loopback bind) and a browser Origin must match SN_HTTP_ALLOWED_ORIGINS (default: loopback origins); otherwise 403.
Probes. GET /healthz → 200 {"status":"ok"} while serving. GET /readyz → 200 when credentials are configured, 503 otherwise. Both answer without the token. GET /readyz?probe=1 (behind the token) also reads one sys_user row and returns 503 when the instance is unreachable; the result is cached for 5 s.
Shutdown. On SIGTERM / SIGINT the listener stops accepting connections, new requests get 503, in-flight tool calls get up to 5 s to finish, then every session is closed and the process exits 0.
Keep-alive. Open SSE streams get a comment every SN_HTTP_KEEPALIVE_MS (25 s).

Quickstart

The fastest path is three lines of Basic auth — set these (in the env file or the real environment) and you are connected:

SN_INSTANCE=dev12345.service-now.com
SN_USER=your.username
SN_PASSWORD=your-password

Everything else is optional tuning; see the full Environment variables reference for the rest.

Past a quick try, prefer OAuth over a stored password. For anything shared or long-lived, run the one-time npx servicenow-mcp-ai login instead — it stores a refresh token, not your password. See Configure credentials → OAuth 2.1.

Verify your setup

Once the three variables are set, confirm the connection before you start:

Run the servicenow_test_connection tool — it reads one sys_user record and reports ok, HTTP status and latency.
Run servicenow_check_capabilities — it previews which admin-restricted sys_* tables the connected user can actually read.

Or do both from the shell in one shot:

npx servicenow-mcp-ai doctor   # checks credentials, reachability and capabilities

Prefer to be asked? npx servicenow-mcp-ai init prompts for the instance, the auth method and the credentials, writes the env file and runs doctor — see Command-line interface.

Configure credentials

Credentials live in ~/.config/servicenow-mcp-ai/.env (or the file SN_ENV_FILE names):

SN_INSTANCE=your-instance.service-now.com
[email protected]
SN_PASSWORD=your-password

SN_INSTANCE accepts dev12345, dev12345.service-now.com or a full https:// URL.

You can also set or change them at runtime by calling the servicenow_set_credentials tool — the new values are written straight back to the env file. Moving a configured profile to a different instance requires user and password in the same call (the stored secrets are never sent to another host), and the change must be confirmed by the client — clients without elicitation support are refused unless SN_ALLOW_UNCONFIRMED_CREDENTIAL_CHANGE=1 is set.

The tool also sets the auth method (auth), the OAuth client id (oauth_client_id) and grant (oauth_grant). Secrets — the API key and the OAuth client secret — are never tool arguments: list them in request_secrets and the server asks for them through an elicitation prompt, so they never appear in a logged tool call, the result or the write journal. A client without elicitation support is refused (the opt-out above does not apply to secrets); set those keys in the env file instead. The instance-change rule follows the resulting auth method: an API-key profile needs a new API key, an OAuth client_credentials profile a new client secret, the OAuth password grant user, password and client secret, Basic / none user and password; bearer-token, refresh_token and jwt_bearer profiles cannot be moved with this tool.

servicenow_get_status (authWarnings), servicenow_list_instances and doctor evaluate each profile against its own auth method — an API-key profile needs no password — and report the method, the OAuth grant, the refresh-token state and the write mode, never a secret value. When the refresh-token grant returns a rotated refresh token, it is written back to the env key it was read from; if the env file cannot be written, the new token is kept in memory (lost on restart) and a warning is logged and shown by get_status / doctor. Values the server writes keep Windows paths literal (backslashes are single-quoted) and a CRLF env file stays CRLF. On Windows the env file inherits its folder's ACL — restrict it yourself (for example icacls .env /inheritance:r /grant:r "%USERNAME%:F"); the server only warns, it never runs icacls.

The env file is resolved in this order: SN_ENV_FILE, then ~/.config/servicenow-mcp-ai/.env (XDG). A project-root .env is deprecated (3.0, B5): if one exists while neither of the two is in use, it is still read and startup warns where to move it. A global/npx install therefore writes to your user config rather than into node_modules. Real environment variables always take precedence over the file.

First run: the model configures itself

At initialize the server sends instructions built from the live configuration: the enabled packages and tool count, the write mode, the active profile and, when nothing is configured, what is missing and how to fix it — plus pointers to the prompts, the reference resources and large-result handling (paging, format "file"). Until then every instance tool fails with code: "NOT_CONFIGURED" and a hint naming servicenow_set_credentials. A first session with an empty env file looks like this (abridged):

instructions  Credentials: NOT configured (missing instance, user, password). Instance tools
              fail with code NOT_CONFIGURED until fixed. To configure: ask the user for
              the instance and credentials, call servicenow_set_credentials, then
              servicenow_test_connection. Never guess or echo a password.
user          How many open P1 incidents do we have?
model         Which instance, user and password should I connect with?
user          dev12345, admin, ••••••
tool call     servicenow_set_credentials { instance: "dev12345", user: "admin", password: … }
tool result   { message: "Credentials saved", profile: "default", configured: true, password: "***" }
tool call     servicenow_test_connection {}
tool result   { ok: true, … }
tool call     servicenow_aggregate { table: "incident", query: "active=true^priority=1" }
model         There are 7 open P1 incidents.

servicenow_get_status then shows the live state: server version, uptime and transport, policy.summary, limits, redaction, the docs directory, write counters, the profile source and profileDetails (per-profile auth mode, write mode and missing keys) — never a secret value.

OAuth 2.1 (Authorization Code + PKCE) — recommended

Register an Authorization Code OAuth API endpoint in ServiceNow with a loopback redirect URL (e.g. http://localhost:53682/callback), set SN_OAUTH_CLIENT_ID (and SN_OAUTH_CLIENT_SECRET for a confidential client), then run the one-time interactive login:

npx servicenow-mcp-ai login

It opens the browser, you approve, and the obtained refresh token is stored in your env file. The server then runs non-interactively (refresh_token grant) — no password is ever stored. PKCE (S256) is always used.

The OAuth 2.0 password grant (ROPC) is deprecated in OAuth 2.1 and disabled on many instances; prefer login. client_credentials and refresh_token grants remain supported for service accounts. See .env.example.

Supported authentication methods

Every inbound REST auth method ServiceNow offers is covered:

Method	`SN_AUTH`	Set	Notes
Basic	`basic`	`SN_USER` / `SN_PASSWORD`	Default.
OAuth 2.1 — Authorization Code + PKCE	`oauth`	`npx servicenow-mcp-ai login`	Recommended. Interactive, stores a refresh token.
OAuth — Client Credentials	`oauth`	`SN_OAUTH_GRANT=client_credentials`	Service-to-service.
OAuth — Refresh Token	`oauth`	`SN_OAUTH_GRANT=refresh_token` + `SN_OAUTH_REFRESH_TOKEN`	Set by `login`.
OAuth — JWT Bearer	`oauth`	`SN_OAUTH_GRANT=jwt_bearer` + `SN_OAUTH_JWT_KEY`	RS256 assertion; no password.
OAuth — Password (ROPC)	`oauth`	`SN_OAUTH_GRANT=password`	Deprecated.
API Key	`apikey`	`SN_API_KEY`	`x-sn-apikey` header.
Bearer token	`token`	`SN_BEARER_TOKEN` or `SN_TOKEN_FILE`	Pre-obtained token, used verbatim. A rejected token (401) re-reads `SN_TOKEN_FILE` once, else fails with `AUTH_EXPIRED`.
Mutual TLS (client cert)	`none` (or layered)	`SN_TLS_CLIENT_CERT` / `_KEY`	Cert maps to a user; needs optional `undici`.

Environment variables

All settings are read from the env file (SN_ENV_FILE, else ~/.config/servicenow-mcp-ai/.env) or the real process environment, which takes precedence. Only the first three are required; the rest are optional tuning knobs. See .env.example for a template. Every value is validated at startup: an invalid one stops the server with an error that names every offending key (3.0, B5), or — with SN_STRICT_SETTINGS=0 — is logged as a warning and the setting keeps its default.

These tables are generated from the settings manifest (src/core/settings-manifest.ts) — edit the manifest, then run npm run docs:env.

Connection and authentication

The instance and its credentials. Only SN_INSTANCE is always required; the auth method is auto-detected from the keys present (API key -> bearer token -> OAuth -> Basic) unless SN_AUTH names it.

Variable	Required	Default	Since	Description
`SN_INSTANCE`	yes	—	1.0.0	Instance name, host, or `https://` URL (`dev12345`, `dev12345.service-now.com`).
`SN_USER`	yes	—	1.0.0	ServiceNow username for Basic auth.
`SN_PASSWORD`	yes	—	1.0.0	ServiceNow password. Never logged or returned by any tool.
`SN_AUTH`	no	auto	1.1.0	Auth method: `basic`, `oauth`, `apikey`, `token` or `none` (cert-only mTLS). Auto-detected from the keys present (API key → bearer → OAuth → Basic).
`SN_API_KEY`	no	—	1.1.0	ServiceNow Inbound API Key, sent as the `x-sn-apikey` header (enables `apikey` mode).
`SN_BEARER_TOKEN`	no	—	1.1.0	A pre-obtained bearer token, sent verbatim as `Authorization: Bearer …` (enables `token` mode).
`SN_TOKEN_FILE`	no	—	next	File holding the bearer token (enables `token` mode; wins over `SN_BEARER_TOKEN`). Re-read once when the instance rejects the token with 401, so an external issuer can rotate it; otherwise the call fails with `AUTH_EXPIRED`.
`SN_TOKEN_EXPIRES_AT`	no	—	next	ISO 8601 expiry of the bearer token. `get_status` / `doctor` warn when less than 24 h remain, when it has passed, or when it cannot be parsed.
`SN_OAUTH_CLIENT_ID`	no	—	1.1.0

Secrets from files

Container secrets (D-5): FILE=/path loads from that file at startup (one trailing newline is trimmed). Setting both and FILE is a startup error; so is an unreadable or empty file. A value loaded this way is never written back to the env file. Per profile: SN_PROFILE_FILE for the ServiceNow secrets.

Variable	Required	Default	Since	Description
`SN_PASSWORD_FILE`	no	—	next	D-5: read `SN_PASSWORD` from this file (Docker / Kubernetes secrets).
`SN_API_KEY_FILE`	no	—	next	D-5: read `SN_API_KEY` from this file (Docker / Kubernetes secrets).
`SN_BEARER_TOKEN_FILE`	no	—	next	D-5: read `SN_BEARER_TOKEN` from this file (Docker / Kubernetes secrets). Read once at startup (`SN_TOKEN_FILE`, re-read on a 401, still wins).
`SN_OAUTH_CLIENT_SECRET_FILE`	no	—	next	D-5: read `SN_OAUTH_CLIENT_SECRET` from this file (Docker / Kubernetes secrets).
`SN_OAUTH_REFRESH_TOKEN_FILE`	no	—	next	D-5: read `SN_OAUTH_REFRESH_TOKEN` from this file (Docker / Kubernetes secrets). A rotated refresh token is then kept in memory only (update the file yourself).
`SN_HTTP_TOKEN_FILE`	no	—	next	D-5: read `SN_HTTP_TOKEN` from this file (Docker / Kubernetes secrets).
`SN_HTTP_OAUTH_INTROSPECTION_SECRET_FILE`	no	—	next	D-5: read `SN_HTTP_OAUTH_INTROSPECTION_SECRET` from this file (Docker / Kubernetes secrets).
`SN_HTTP_OAUTH_TOKEN_KEY_FILE`	no	—	next	D-5: read `SN_HTTP_OAUTH_TOKEN_KEY` from this file (Docker / Kubernetes secrets).

Profiles and the env file

The bare SN_INSTANCE / SN_USER / SN_PASSWORD keys are the 'default' profile. More instances live under SN_PROFILE__* keys; switch with SN_ACTIVE_PROFILE or the servicenow_use_instance tool.

Variable	Required	Default	Since	Description
`SN_PROFILE_<NAME>_*`	no	—	1.1.0	Named connection profiles: `SN_PROFILE_DEV_INSTANCE` / `_USER` / `_PASSWORD` define profile `dev`. The bare `SN_INSTANCE`/`SN_USER`/`SN_PASSWORD` keys are the `default` profile. The auth, policy, write-mode, `ENV`, `PROD_WRITES` and `UPDATE_SET` settings take the same prefix. Example: `SN_PROFILE_DEV_INSTANCE=dev12345.service-now.com`, `SN_PROFILE_DEV_USER=admin`, `SN_PROFILE_DEV_PASSWORD=dev-password`.
`SN_ACTIVE_PROFILE`	no	`default`	1.1.0	Which profile tools use. Switch at runtime with `servicenow_use_instance` (written to the env file only with `persist: true`).
`SN_ENV_FILE`	no	`~/.config/servicenow-mcp-ai/.env`	1.1.0	Explicit path to the env file to read/write. Otherwise the server uses `$XDG_CONFIG_HOME/servicenow-mcp-ai/.env` (`~/.config/…`). A project-root `.env` next to the installed package is still read when neither is in play, as a deprecated fallback (B5) with a startup warning naming where to move it. `doctor` prints the chosen file and why.

Network, TLS and resilience

Timeouts, retries, the host allow-list, the outbound proxy, mutual TLS and the per-host queue and circuit breaker. They govern every REST client of the server. The proxy and mutual TLS need the optional undici package.

Variable	Required	Default	Since	Description
`SN_TIMEOUT_MS`	no	`30000`	1.1.0	Per-request timeout in milliseconds.
`SN_MAX_RETRIES`	no	`2`	1.1.0	Retries for transient failures (429/5xx, network errors). Non-idempotent writes are only retried on connect errors.
`SN_RETRY_AFTER_MAX_MS`	no	`60000`	next	Upper bound honoured for a `Retry-After` header on 429/503; a larger value is clamped so a misbehaving upstream cannot park the client for minutes.
`SN_DEADLINE_MS`	no	max(120000, 2 × `SN_TIMEOUT_MS`)	next	Total wall-clock budget for one logical request across retries, backoff, queue wait and OAuth re-auth. A retry that cannot fit into the remaining budget is not attempted — the call fails with code `DEADLINE_EXCEEDED`.
`SN_ALLOWED_HOSTS`	no	—	1.1.0	Comma-separated allow-list of permitted hosts (for custom or sovereign-cloud domains). When set, only matching hosts are contacted. When unset, only `*.service-now.com` instances are allowed and internal/loopback hosts are blocked (SSRF guard). An entry may carry a port (`host:8443`) or be a bracketed IPv6 literal (`[2001:db8::1]`); an explicit non-443 port or an IPv6 literal in the instance value is accepted only when such an entry matches it — never under the default policy.
`SN_MAX_BODY_BYTES`	no	`52428800`	next	Largest response body (bytes) read into memory; a larger declared or streamed body fails with `RESPONSE_TOO_LARGE`. Redirects are never followed — a 3xx fails with `REDIRECT_BLOCKED` naming the target host.
`SN_HTTPS_PROXY`	no	—	next	Outbound HTTPS proxy URL (`http://user:pass@proxy:3128`) for all ServiceNow and OAuth traffic; needs the optional package. When unset, the ambient / variables are honoured together with ; itself is explicit and ignores . Proxy credentials are never logged.

Tool packages

Which tools are registered. The admin tools (set_credentials, get_status, use_instance) are always on.

Variable	Required	Default	Since	Description
`SN_TOOL_PACKAGES`	no	`discovery`	1.0.0	Comma/space-separated tool packages or profiles to enable. Profiles: `discovery` (default; `core`, the 2.x default, adds `attachment`), `all` and the presets `reader` \
`SN_PACKAGES_DENY`	no	—	1.0.0	Comma/space-separated packages to exclude even if enabled by `SN_TOOL_PACKAGES`. The only way to block plugin APIs (catalog, change, knowledge…) — the table policy does not see them.
`SN_PACKAGES_READONLY`	no	—	1.0.0	Comma/space-separated packages whose write tools are not registered; their read tools stay. Per-package complement to the global `SN_READONLY`.
`SN_CODESEARCH`	no	`false`	1.1.0	Opt in to the Code Search API (`sn_codesearch`) for `servicenow_search_code` (FT-7). When `true` and the plugin is active it replaces the LIKE iteration; falls back to LIKE on any failure.
`SN_EXPERIMENTAL_TASKS`	no	`0`	next	M-9, experimental: `1` adds an optional `run_as_task:true` argument to `snapshot_instance`, `compare_instances`, `run_atf`, `check_code_health`, `document_app`, `document_instance` and `query_table` (`format:"file"` only). Such a call returns an MCP task handle at once (`_meta["io.modelcontextprotocol/related-task"]`); the client polls `tasks/get`, reads `tasks/result` (kept 1 h, redacted) or stops it with `tasks/cancel`. Off: schemas unchanged. Built on the SDK's experimental task API.
`SN_MCP_APPS`

Access policy and write safety

Least-privilege table policy, plan-and-apply writes, destructive-write confirmation, per-session caps, prod profiles, update-set binding and the upload / email / SDK-managed-scope guards.

Variable	Required	Default	Since	Description
`SN_TABLES_ALLOW`	no	—	1.1.0	Comma-separated table allowlist; when set, only these tables are reachable.
`SN_TABLES_DENY`	no	—	1.1.0	Comma-separated table denylist; always wins over the allowlist.
`SN_READONLY`	no	`false`	1.1.0	When truthy, refuse every create/update/delete.
`SN_WRITE_MODE`	no	`plan`	2.0.0	`plan` (default) previews a write as a before/after diff without mutating; `apply` executes; passing `apply:true` forces a single call.
`SN_COMPAT`	no	`3`	next	Upgrade bridge (owner, 2026-10-14): `2` keeps the 2.x defaults for every one of these settings left unset — `SN_PROTECTED_TABLES_WRITE=allow`, `SN_DESTRUCTIVE_CONFIRM=off`, `SN_BATCH_UNMAPPED=allow`, `SN_LEGACY_TOOL_NAMES=1` and `SN_TOOL_PACKAGES=core` (discovery plus `attachment`) — and an invalid value warns and keeps its default instead of stopping the server (`SN_STRICT_SETTINGS=0`). A setting you set yourself always wins. `servicenow-mcp-ai migrate` adds it when it converts a 2.x env file. `3` (the default) uses the 3.0 defaults. Meant for the migration, not as a permanent setting.
`SN_DESTRUCTIVE_CONFIRM`	no	`token`	next	H-3: confirmation for a destructive `apply:true` (`delete_record`, `delete_attachment`, a writing `batch`, `send_email`, `order_catalog_item`, `revert_write`, `upsert_artifact`, `check_change_conflicts` with `calculate:true`) in plan mode. (the 3.0 default, B4): the plan preview returns a single-use and the apply must pass it back with the same arguments — an apply with no token returns that preview and its token instead (nothing runs), a wrong, used or expired one is ; : plus a confirmation prompt on clients with elicitation (a decline is , journaled as refused). bypasses it, except on a profile marked (), which is always at least and is confirmed in apply mode too. is the explicit opt-out (the pre-3.0 behaviour).

Results, redaction and exports

Result size budgets, output shaping, redaction of record values, the write journal and CSV export safety.

Variable	Required	Default	Since	Description
`SN_MAX_RECORDS`	no	`10000`	1.1.0	Hard cap on records returned by a `fetchAll` query.
`SN_MAX_RESULT_CHARS`	no	`48000`	1.1.0	Character budget for a tool result (48,000 since O-21 (b), under Claude Code's 50,000 threshold). A larger result goes to a file while `SN_OVERSIZE_TO_FILE` is on; otherwise it is shrunk with a note naming `format:"file"`, and a snapshot, compare or diagram result is returned in full with a `note`.
`SN_OVERSIZE_TO_FILE`	no	`true`	next	S-11 / N-61 (default on since O-21 (b)): write a `query_table` (JSON lines), snapshot, compare or diagram result over `SN_MAX_RESULT_CHARS` to a file under `SN_DOCS_DIR` (`<profile>/exports/`, `<profile>/diagrams/`) and return `{path, bytes, preview}` instead.
`SN_RESULT_SIZE_HINTS`	no	`true`	next	N-65 (default on, O-21 (c)): the large readers (`document_`, `snapshot_instance`, `compare_`, `get_script`) carry `_meta["anthropic/maxResultSizeChars"]` = `SN_MAX_RESULT_CHARS` in `tools/list`. Set `false` to drop the hints.
`SN_STRUCTURED`	no	`true`	next	N-39 (default on, O-21 (d)): tools with an output shape publish `outputSchema` in `tools/list` and answer with `structuredContent` next to the JSON text. Set `false` to drop both: every result then carries its payload once, as text, and `tools/list` is smaller.
`SN_INCLUDE_REF_LINKS`	no	`false`

Caching

The schema reads cache and the capability / plugin-API probes.

Variable	Required	Default	Since	Description
`SN_RECORD_WATCH_INTERVAL_MS`	no	`30000`	next	N-10: poll interval of a record-watch subscription (`servicenow://profiles/<profile>/records/<table>/<sys_id>`); each poll reads `sys_updated_on` / `sys_mod_count`. Floor 30000.
`SN_RECORD_WATCH_MAX_PER_SESSION`	no	`10`	next	N-10: record-watch subscriptions one client session may hold; one more is refused with `WATCH_LIMIT`.
`SN_RECORD_WATCH_MAX`	no	`50`	next	N-10: record-watch subscriptions across the process (every session); one more is refused with `WATCH_LIMIT`.
`SN_SCHEMA_CACHE_TTL_SEC`	no	`300`	1.1.0	TTL for the near-static schema reads cache (`list_tables`, `describe_table`, `get_cmdb_meta`). `0` disables caching.
`SN_SCHEMA_CACHE_MAX`	no	`256`	next	Maximum entries in the schema reads cache; when full, the least-recently-used entry is evicted. Counters (`size`, `hits`, `misses`, `evictions`) appear in `get_status` under `schemaCache`.
`SN_CAPABILITY_TTL_MS`	no	`600000`	next	How long a successful capability probe is cached — the `servicenow_check_capabilities` matrix and the plugin-API availability (CI/CD, Code Search, Batch…). Pass `refresh: true` to re-probe sooner.
`SN_PLUGIN_NEGATIVE_TTL_MS`	no	`60000`	next	How long a failed capability probe (HTTP 401/403/404/5xx) or a missing plugin API is cached before it is tried again. Transport errors are never cached.

Docs store and diagrams

The local Markdown docs store (also home of the write journal — keep it out of version control) and the generated Mermaid diagrams.

Variable	Required	Default	Since	Description
`SN_DOCS_DIR`	no	`docs/instance`	1.0.0	Directory the `docs` package reads/writes Markdown in. Relative paths resolve against the working directory. It also holds the per-profile write journal — add `docs/instance/` to `.gitignore` in any repository you run the server from.
`SN_DOCS_MAX_FILE_BYTES`	no	`5242880`	next	Per-file size cap for the docs tools: larger writes are refused, reads return the first bytes with `truncated: true`, search skips the file.
`SN_DOCS_STALE_DAYS`	no	`30`	next	`servicenow_list_docs` flags a generated document `stale` when its `sn_generated_at` is older than this many days.
`SN_DOCS_SEARCH_MAX`	no	`200`	next	Most matches `servicenow_search_docs` returns; past it the result carries `truncated: true`.
`SN_DIAGRAM_MAX_NODES`	no	`200`	next	Node cap for the generated Mermaid diagrams (table flow, event trace, where-used; tables in a detailed ER diagram). Nodes past it fold into one `+N more` node.

HTTP transport

stdio (default, one local client) or Streamable HTTP for remote and agent clients. Securing the HTTP endpoint (TLS, auth, network) is the operator's job.

Variable	Required	Default	Since	Description
`SN_TRANSPORT`	no	`stdio`	2.0.0	DF-6: `stdio` (default) or `http` (Streamable HTTP for remote/agent clients).
`SN_PORT`	no	`3000`	2.0.0	DF-6: TCP port for the http transport.
`SN_HTTP_HOST`	no	`127.0.0.1`	2.0.0	DF-6: bind address for the http transport (loopback by default).
`SN_HTTP_TOKEN`	no	—	2.0.0	DF-6: when set, http requests must send `Authorization: Bearer <token>`. Required whenever `SN_HTTP_HOST` is not loopback (e.g. `0.0.0.0` in the Docker image) — without it every client that reaches the port is accepted, and a warning is logged.
`SN_HTTP_OAUTH_ISSUER`	no	—	next	N-17: issuer of the OAuth 2.1 / OpenID Connect authorization server whose JWT access tokens the http transport accepts (signature checked against its JWKS; `iss`, `aud`, `exp`, `nbf` and scopes enforced). Enables RFC 9728 metadata at `/.well-known/oauth-protected-resource`. Requires `SN_HTTP_OAUTH_RESOURCE`; `SN_HTTP_TOKEN` is still accepted next to it.
`SN_HTTP_OAUTH_RESOURCE`	no	—	next	N-17: this server's canonical public URI (RFC 8707 resource indicator). A token is accepted only when its `aud` names it (or an `SN_HTTP_OAUTH_AUDIENCE` value).
`SN_HTTP_OAUTH_AUDIENCE`	no	—	next	N-17: extra `aud` values accepted besides `SN_HTTP_OAUTH_RESOURCE`, for an authorization server that issues its own audience identifiers.

Logging

The stderr log, the optional log file and the log lines mirrored to the MCP client.

Variable	Required	Default	Since	Description
`SN_LOG_LEVEL`	no	`info`	1.1.0	Log verbosity on stderr: `error`, `warn`, `info`, `debug`. The legacy `LOG_LEVEL` is read when this is unset. Also read as `LOG_LEVEL`.
`SN_LOG_FORMAT`	no	`json`	next	E-5: stderr log line format — `json` (one object per line) or `text` (`HH:MM:SS level message key=value`).
`SN_LOG_FILE`	no	—	next	E-5: also append every log line (JSON Lines, redacted, mode 0600) to this file, with size-based rotation (`<file>.1` … `<file>.5`). Stderr keeps working.
`SN_LOG_FILE_MAX_BYTES`	no	`10485760`	next	E-5: rotation threshold for `SN_LOG_FILE` (bytes).
`SN_LOG_NOTIFY_RATE`	no	`20`	next	M-8: log notifications per second and client session over the MCP logging capability (burst 50, or the rate if larger). Lines over it are counted and reported in one "N log messages suppressed" warning per minute; stderr is never throttled. `0` = no limit.
`SN_OTEL`	no	off	next	N-55: map the tool-call and HTTP `diagnostics_channel` events to OpenTelemetry spans (MCP / GenAI semantic conventions). Needs the optional peer dependency `@opentelemetry/api` and an OpenTelemetry SDK registered in the process (e.g. `node --import`); without the package one warning is logged and nothing else changes.
`SN_OTEL_PROPAGATE`	no	off	next	N-55: send W3C `traceparent` / `tracestate` headers on outbound ServiceNow REST requests — the HTTP client span's context when is on, otherwise the context the client sent in . Off: trace ids never leave the server.

Settings validation

Every setting is validated at startup. An invalid safety value is a startup error; an invalid tuning value is logged as a warning and the setting keeps its default (see SN_STRICT_SETTINGS).

Variable	Required	Default	Since	Description
`SN_STRICT_SETTINGS`	no	safety settings only	next	E-4 / B5: which invalid setting values (a non-number, an unknown enum value, an out-of-range port…) stop the server with a startup error that names every offending key. Unset: only safety settings — connection, profiles, packages, policy, transport and the trust / privacy keys (`SN_ALLOWED_HOSTS`, `SN_TLS_`, `SN_REDACT_`, `SN_CSV_FORMULA_GUARD`); an invalid tuning value (timeouts, caps, caches, logging) logs a warning and keeps its default, as in 2.x. `1`: every invalid value is an error. `0`: none is (the default under `SN_COMPAT=2`). Unknown `SN_*` keys stay warnings.

Standard variables

Conventional variables outside the SN_ namespace that the server also honours.

Variable	Required	Default	Since	Description
`HTTPS_PROXY`	no	—	next	Standard proxy for HTTPS traffic, honoured when `SN_HTTPS_PROXY` is unset (with `NO_PROXY`). Also read as `https_proxy`.
`HTTP_PROXY`	no	—	next	Fallback proxy when `HTTPS_PROXY` is unset. Also read as `http_proxy`.
`NO_PROXY`	no	—	next	Hosts that bypass `HTTPS_PROXY` / `HTTP_PROXY` (never `SN_HTTPS_PROXY`). Also read as `no_proxy`.
`XDG_CONFIG_HOME`	no	`~/.config`	1.1.0	Base directory of the default env file (`$XDG_CONFIG_HOME/servicenow-mcp-ai/.env`).

Secrets from files

Every secret setting can be read from a file, the convention of Docker, Compose / Swarm and Kubernetes secrets: set <KEY>_FILE to a path and the server loads <KEY> from it at startup. This covers SN_PASSWORD, SN_API_KEY, SN_BEARER_TOKEN, SN_OAUTH_CLIENT_SECRET, SN_OAUTH_REFRESH_TOKEN and SN_HTTP_TOKEN, plus the per-profile forms (SN_PROFILE_PROD_PASSWORD_FILE, SN_PROFILE_PROD_API_KEY_FILE, …).

One trailing newline is trimmed, so echo secret > file works; other whitespace is kept.
Setting both <KEY> and <KEY>_FILE is a startup error that names the pair — the server never picks one silently.
An unreadable or empty file is a startup error that names the setting and the reason, never the content.
A value loaded from a file is never written back to the env file: servicenow_set_credentials and OAuth refresh-token rotation refuse to persist it (a rotated refresh token stays in memory with a warning) — update the file.
The existing file settings keep their meaning: SN_TOKEN_FILE (bearer token re-read on a 401), SN_OAUTH_JWT_KEY_FILE and the SN_TLS_*_FILE PEM paths are paths the server reads itself, not <KEY>_FILE sources.

Two-axis access policy

Access is controlled on two independent axes: tables and tool packages.

Axis	Enable / deny / read-only	Example
Tables	`SN_TABLES_ALLOW` / `SN_TABLES_DENY` / `SN_READONLY`	`SN_TABLES_DENY=change_request` blocks the Table API and (since H-4) the Change tools, which check their backing table.
Packages	`SN_TOOL_PACKAGES` / `SN_PACKAGES_DENY` / `SN_PACKAGES_READONLY`	`SN_PACKAGES_DENY=change` removes the Change Management tools and blocks the `sn_chg_rest` plugin API, also inside a batch.

Since H-4 the plugin-backed tools (Change, Catalog, Knowledge, Email, ATF) and attachments (through the parent record's table) obey the table axis too; the package axis still removes whole surfaces. See Security notes for the full model (including how the Batch API obeys both axes).

List syntax: table lists (SN_TABLES_ALLOW / SN_TABLES_DENY) are comma-separated; package lists (SN_TOOL_PACKAGES, SN_PACKAGES_DENY, SN_PACKAGES_READONLY) accept commas or whitespace. Surrounding spaces are trimmed in both, and table matching is case-insensitive — so SN_TABLES_DENY=Change_Request, sys_user works. Since H-11 a table entry may be a pattern (* any run, ? one character): SN_TABLES_DENY=sys_* blocks sys_user and leaves incident alone. The order is: an exact deny, an exact allow, a pattern deny, the protected tables (writes; since 3.0 they need the call's own apply: true — SN_PROTECTED_TABLES_WRITE=confirm; deny refuses them, allow lifts the rule), then the allowlist's patterns. Ask servicenow_explain_policy({table, action}) which rule decides, or read servicenow://policy.

Run / debug

VS Code: open the Command Palette and start the server defined in .vscode/mcp.json, then use it from Chat.
MCP Inspector: npm run inspector
Directly: npm start

Observability

Status. servicenow_get_status carries an observability block: per-tool {count, errors, p50, p95, totalMs} (percentiles in ms over each tool's last 256 calls — memory stays bounded) plus result sizes {bytesTotal, textBytes, structuredBytes, bytesP50, bytesP95} (UTF-8 bytes of the text blocks and of structuredContent, the wire cost of each tool), schema-cache hits/misses, per-host retry counters, queue limits and occupancy, circuit-breaker state and the last X-RateLimit-* headers each host sent. It never calls the instance.
Logs. Logs go to stderr only (stdout is the MCP protocol). SN_LOG_FORMAT=text switches from JSON lines to a human-readable format; SN_LOG_FILE also appends JSON lines to a size-rotated file. Credential-named fields (password, token, authorization, …) are masked in every sink, and the SN_REDACT_FIELDS / SN_REDACT_PII rules and the secret-column masking apply on top.

Tracing hooks. Every tool call and the request loop publish on node:diagnostics_channel, so an OpenTelemetry (or any) subscriber can attach without a dependency on this server. Messages are built only while a channel has a subscriber:

Channel	When	Message fields
`servicenow-mcp:mcp.tool.call.start`	a tool call begins	`id`, `tool`, `package`, `requestId`, and `sessionId` / `traceparent` / `tracestate` when known
`servicenow-mcp:mcp.tool.call.end`	it returned a successful result	the start fields plus `profile`, `outcome` (`ok`), `ms`, `resultBytes`
`servicenow-mcp:mcp.tool.call.error`	it returned an error result or threw	the start fields plus `profile`, `outcome` (`error` / `cancelled`), `ms`, and / or

Command-line interface

The published servicenow-mcp-ai binary (run it directly, or via npx servicenow-mcp-ai) starts the MCP server when it is given no command, and otherwise runs one of the commands below and exits. Connection settings come from environment variables / the env file (see Environment variables). servicenow-mcp-ai --help lists everything; --version prints the version. An unknown command or option prints the usage on stderr and exits 2 — it never starts the server.

| Command | Options | What it does | Exit codes

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install Servicenow MCP Ai?

Does Servicenow MCP Ai need an API key?

What transport does Servicenow MCP Ai use?

When was Servicenow MCP Ai last checked?

Documentation

servicenow-mcp-ai — ServiceNow MCP Server

Quick demo

Features

Requirements

Setup

Install in your MCP client

Install via MCP bundle (.mcpb)

Docker

HTTP transport: sessions, probes and shutdown

Quickstart

Verify your setup

Configure credentials

First run: the model configures itself

OAuth 2.1 (Authorization Code + PKCE) — recommended

Supported authentication methods

Environment variables

Connection and authentication

Secrets from files

Profiles and the env file

Network, TLS and resilience

Tool packages

Access policy and write safety

Results, redaction and exports

Caching

Docs store and diagrams

HTTP transport

Logging

Settings validation

Standard variables

Secrets from files

Two-axis access policy

Run / debug

Observability

Command-line interface