MFA ServiceNow MCP — LLM Setup Guide¶

This file is for LLM agents, not humans. A human pastes the curl command below into their AI coding assistant. The LLM reads this file and walks the user through setup interactively.

How to use (for humans)¶

Paste this into your AI coding assistant (Claude Code, Cursor, Codex, OpenCode, Windsurf, etc.):

Install and configure mfa-servicenow-mcp by following:
curl -s https://raw.githubusercontent.com/jshsakura/mfa-servicenow-mcp/main/docs/llm-setup.md

That's it. Your AI handles the rest.

Instructions for the LLM agent¶

You are setting up mfa-servicenow-mcp — an MCP server that gives AI agents access to ServiceNow platforms with MFA/SSO support. Follow every step below in order. Ask the user questions interactively; do NOT assume values.

Step 0 — Detect environment¶

Detect the operating system: run uname -s 2>/dev/null || echo Windows
Detect which AI client you are running inside. Use this mapping:

Signal	Client
You have access to `claude mcp add` or `.claude/` directory	claude-code
You are inside Cursor IDE or `.cursor/` exists	cursor
You have access to OpenCode CLI or `opencode.json` exists	opencode
You are inside Codex CLI or `.codex/` exists	codex
You are inside Windsurf IDE or `.windsurf/` exists	windsurf
You are inside VS Code with Copilot	vscode-copilot
You are inside Antigravity	antigravity
You are inside Zed editor or `~/.config/zed/` exists	zed
None of the above	Ask the user which client they use

If you cannot auto-detect, ask:

Which AI coding tool are you using? 1. Claude Code 2. Claude Desktop 3. Cursor 4. OpenCode 5. Codex (OpenAI) 6. Windsurf 7. VS Code Copilot 8. Zed 9. AntiGravity (Google)

Store the result as $CLIENT.

Step 1 — Install uv¶

Check if uv is already installed: uv --version

If NOT installed:

macOS / Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

After install, verify: uv --version If the command is not found, the user may need to restart their shell or add ~/.local/bin to PATH.

Step 2 — Install Playwright Chromium (MANDATORY, do NOT skip)¶

Hard dependency. Skipping this is the #1 reason setups fail in the field. Do not assume it's already installed. Do not let the user defer it. Do not proceed to Step 3 until this succeeds.

2.1 — Check whether Chromium is already installed

macOS: ls ~/Library/Caches/ms-playwright/chromium-*/chrome-mac/Chromium.app/Contents/MacOS/Chromium 2>/dev/null
Linux: ls ~/.cache/ms-playwright/chromium-*/chrome-linux/chrome 2>/dev/null
Windows (PowerShell): Get-ChildItem "$env:USERPROFILE\AppData\Local\ms-playwright\chromium-*\chrome-win\chrome.exe" -ErrorAction SilentlyContinue

If a path is printed, Chromium is already installed — skip to Step 3.

2.2 — Install Chromium

If 2.1 found nothing, install Chromium through uvx so Playwright setup uses the same execution style as the MCP server:

uvx --with playwright playwright install chromium

This downloads ~150 MB the first time. On a slow link it can take several minutes — that is normal. Do not abort early. Show the user a progress message ("Downloading Chromium for ServiceNow MFA login — this can take a few minutes on slow networks…") so they understand the wait.

If uvx package execution is blocked, switch to the release zip/exe path:

Download servicenow-mcp-<platform>-<version>.zip from GitHub Releases. There is no installer script — the zip contains the PyInstaller-built executable only.
Extract the executable into any stable folder the user controls (e.g. ~/apps/servicenow-mcp/).
If the browser download is blocked too, download ms-playwright-chromium-<platform>-<version>.zip from the same release and extract it to a sibling folder named ms-playwright/ — the executable auto-detects that layout at startup and sets PLAYWRIGHT_BROWSERS_PATH to it for its own process.
Set the MCP client command to the absolute path of that executable. The env block is identical to the uvx setup.

2.3 — Verify and stop on failure

Re-run the check from 2.1. If the binary is still missing, STOP the setup and report the failure to the user with the exact command output. Common causes:

Corporate policy blocking package or browser downloads; use the release zip/exe path
Antivirus quarantining the Chromium archive
Disk full

Do not continue to Step 3 with Chromium missing. The MCP server will appear to start, the first tool call will hang, and the user's login window will never open — exactly the failure mode this step exists to prevent.

Why this matters (context for the agent — do not surface to the user unless asked): the runtime tries to fall back to "install on demand" when Chromium is absent, but on slow connections that download exceeds the MCP host's tool-call timeout. The user sees no login window, no error UI, and assumes the server is broken. Pre-installing here makes the first tool call subsecond.

Step 3 — Collect user configuration¶

Ask the user these questions one by one. Provide defaults in brackets.

ServiceNow instance URL

What is your ServiceNow instance URL? Example: https://your-company.service-now.com

Store as $INSTANCE_URL. Validate it looks like a URL.

Authentication type

How do you authenticate to ServiceNow? 1. browser — MFA/SSO via real browser (recommended) 2. basic — Username + password 3. oauth — OAuth 2.0 client credentials 4. api_key — REST API key

Store as $AUTH_TYPE. Default: browser

Credentials (optional, for form pre-fill with browser auth)

(Optional) Enter your ServiceNow username to pre-fill the login form. Leave blank to type it manually each time.

Store as $USERNAME (may be empty). If provided, also ask for $PASSWORD.

Tool package

Which tool package do you need? 1. standard — Core tools (incidents, changes, catalog) [default] 2. service_desk — Standard + assignment, SLA, escalation 3. portal_developer — Standard + portal widgets, pages, themes 4. platform_developer — Standard + scripts, flows, update sets 5. full — Broadest packaged surface with bundled workflows (53 tools)

Store as $TOOL_PACKAGE. Default: standard

Headless browser

Run browser in headless mode? (no visible window) Recommended: No (so you can see and complete MFA prompts)

Store as $HEADLESS. Default: false

Step 4 — Run the installer command¶

IMPORTANT: Always default to project-local installation when the client supports it. Use --scope global only if the user explicitly asks for a global install.

Build a single installer command and run it from the current project root. The installer now owns: - client-specific config file paths - merge/update behavior for existing config files - optional skills installation for supported clients

Base command:

uvx --with playwright --from mfa-servicenow-mcp servicenow-mcp setup "$CLIENT" \
  --instance-url "$INSTANCE_URL" \
  --auth-type "$AUTH_TYPE" \
  --tool-package "$TOOL_PACKAGE" \
  --browser-headless "$HEADLESS"

Add flags only when needed:

If the user provided username: --username "$USERNAME"
If the user provided password: --password "$PASSWORD"
For OAuth: add --client-id, --client-secret, and optionally --token-url
For API key: add --api-key and optionally --api-key-header
If the user wants global install: add --scope global
If the user does not want skills: add --skip-skills

Examples:

uvx --with playwright --from mfa-servicenow-mcp servicenow-mcp setup opencode \
  --instance-url "https://your-instance.service-now.com"

uvx --with playwright --from mfa-servicenow-mcp servicenow-mcp setup codex \
  --instance-url "https://your-instance.service-now.com" \
  --auth-type basic \
  --username "your-username" \
  --password "your-password"

uvx --with playwright --from mfa-servicenow-mcp servicenow-mcp setup claude-code \
  --instance-url "https://your-instance.service-now.com" \
  --scope global \
  --skip-skills

Step 5 — Verify installation¶

Confirm the installer exited successfully
Read the config file path reported by the installer summary
If skills were installed, confirm the installed skills directory exists
Do not manually rewrite the config unless the installer failed and you are explicitly repairing it

Step 6 — Tell the user what happens next¶

After installation, tell the user:

Installation is complete! Restart your AI client (or reload MCP servers) so it picks up the new configuration.

On the first browser-authenticated tool call, a browser window will open for MFA/SSO login. After login, try: Run a health check on my ServiceNow instance Full docs: https://jshsakura.github.io/mfa-servicenow-mcp/

Do not attempt to call ServiceNow MCP tools in the current session after setup. The client must restart first.

Important notes for the LLM¶

Never hardcode credentials in config files without asking. If the user skips credentials, omit them entirely from the config.
The installer merges into existing config files. Do not hand-roll config merges unless recovery is needed.
Windows paths use backslashes. Use the correct path separator for the OS.
If any step fails, diagnose the error and help the user fix it before moving on.
Keep the conversation friendly and concise. Don't dump walls of text.
After installation, do NOT try to test MCP tools. Just tell the user to restart and they're good to go.