How to connect Claude Code to a ServiceNow developer instance
Install the OnlyFlows ServiceNow MCP server, connect it to your personal developer instance (PDI) with read-only access, register it with Claude Code, and check the connection. You don't need Now Assist or a paid ServiceNow license.
Run npm install -g @onlyflows/servicenow-mcp, then servicenow-mcp-setup. Name the profile pdi, enter your instance host and credential, keep the default read-only grant, and let setup register Claude Code. Start claude, run /mcp to confirm servicenow-mcp is connected, and ask: “On pdi, show me the five most recent incidents.”
What you need
- A ServiceNow personal developer instance, free from developer.servicenow.com, or another instance you're allowed to connect to.
- Node.js 20 or newer.
- Claude Code installed, with the
claudecommand on your PATH. - A ServiceNow account for the server to sign in as. A dedicated integration user is safer than admin (step 2).
Safe defaults
- Setup grants reads on
incidentonly and no writes, unless you choose otherwise. - Every other table is denied until you grant it with
servicenow-mcp-setup grant. sn_delete,sn_batch, andsn_atfare never granted implicitly; you name them with--tools.- Your credential is checked against the instance, then stored encrypted in an owner-only
~/.servicenow-mcpdirectory. Claude Code's configuration never holds it. - ServiceNow ACLs still apply, so an integration user with narrow roles narrows the agent too.
Step-by-step setup
- 1
Wake your developer instance and note its host
Sign in at developer.servicenow.com and open your instance. Personal developer instances hibernate when they sit idle, and a sleeping instance makes setup fail with a 404 or a timeout, so wake it first and wait until it loads in a browser.
Note the host name, for example
dev12345.service-now.com. Setup accepts the bare host. - 2
Create an integration user (recommended)
You can connect as the instance admin, but then the agent can reach anything admin can, limited only by your table grants. A dedicated user keeps ServiceNow's own ACLs working as a second boundary.
In the instance, open User Administration > Users and create a user such as
mcp.integration. Set a password, tick Web service access only, and give it the roles your work needs:itilcovers incident, problem, and change. While you're trying things out, addsnc_read_onlyas well, so ServiceNow blocks writes even if a grant allows them.Web service access only also keeps the account usable for API calls if your instance enforces ServiceNow's basic authentication restrictions (KB3096078).
- 3
Install the server
Check that
node --versionprints v20 or newer, then install the package globally. A global install puts theservicenow-mcpcommand on your PATH, which is where your client looks for it.npm install -g @onlyflows/servicenow-mcpTo try it without a global install,
npx @onlyflows/servicenow-mcp@latest setupruns the same setup wizard. - 4
Run setup with read-only access
Run the setup wizard. It asks for a profile name, your instance, and a credential, checks the credential against the instance before saving anything, then asks which tables to grant. The credential is typed at a hidden prompt, so it never lands in your shell history.
Name the profile
pdi, keep the default read grant (incidentonly), and keep the default of no writes:servicenow-mcp-setupExample answers
Profile name [dev]: pdi ServiceNow instance (for example dev12345.service-now.com): dev12345.service-now.com Authentication: 1) basic (default) 2) oauth 3) apikey Choice [1]: 1 How should the credential be stored?: 1) encrypted (default) 2) reference Choice [1]: 1 ServiceNow username: mcp.integration credential: Verifying against the instance... ok https://dev12345.service-now.com accepted the credential. Tables to allow for READS: 1) Just incident (default) ... Choice [1]: 1 Tables to allow for WRITES: ... 5) None (default) Choice [5]: 5 Wrote profile pdi.Setup ends by running the same checks as
servicenow-mcp-setup doctor. Every line should start withok.If the
claudecommand is on your PATH, setup then offers to register the server with Claude Code. Answery.Basic authentication is the quickest path on a developer instance. ServiceNow is phasing it out for API calls, so if your instance rejects it, choose
oauthinstead and create an OAuth API endpoint client under System OAuth > Application Registry first. - 5
Register the server with Claude Code (if setup didn't)
If you skipped the prompt or installed Claude Code later, register the server yourself.
--scope usermakes it available in every project, and stdio is the default transport, so there's no transport flag to pass.claude mcp add --scope user servicenow-mcp -- servicenow-mcpCheck that it's registered
claude mcp listOr share it with a project: check in .mcp.json at the project root
{ "mcpServers": { "servicenow-mcp": { "command": "servicenow-mcp", "args": [] } } }The
.mcp.jsonentry only tells Claude Code what to start, never a credential. Each teammate runsservicenow-mcp-setupwith their own account. - 6
Check the connection
Run the doctor against your profile. It checks your Node version, that
servicenow-mcpresolves on your PATH, file permissions, the profile, the stored credential, and table access, and prints a fix for anything that fails.servicenow-mcp-setup doctor --profile pdiThen start claude, run /mcp to confirm servicenow-mcp is connected, and ask:
On pdi, show me the five most recent incidents with their number and short description.Claude Code asks before it runs the tool. It should call
sn_querywithprofile: "pdi"and tableincident. Each call also writes one audit line to the server log Claude Code keeps, with no credentials or record contents in it. - 7
Tell Claude Code which profile to use
Every tool call must name a profile; there's no default. Instead of starting every prompt with “on pdi”, add a line to the
CLAUDE.mdfile in your project:CLAUDE.md
ServiceNow: use the servicenow-mcp profile "pdi". It is a personal developer instance with read-only access. - 8
Widen access one grant at a time
When you need more, add a grant instead of opening every table. Grants are additive, validated when you run them, and
--dry-runprints the result without writing it.Read another table
servicenow-mcp-setup grant --profile pdi --read problemQuery CIs and walk CMDB relationships
servicenow-mcp-setup grant --profile pdi --read cmdb_ci --tools sn_query,sn_relationshipsLet the agent append work notes to incidents, and write nothing else
servicenow-mcp-setup grant --profile pdi --write incident --tools sn_incident_add_work_notePreview allowing incident create and update
servicenow-mcp-setup grant --profile pdi --write incident --dry-runA write grant without
--toolsallowssn_createandsn_updateon that table.sn_delete,sn_batch, andsn_atfare never granted implicitly; you have to name them with--tools. Since 2.1,sn_createandsn_updatewrite to any table a profile grants for writes, so keep write grants narrow.Restart Claude Code after a grant, or start a new session, because it reads the profile when it starts the server.
Troubleshooting
Start with servicenow-mcp-setup doctor: it checks the install end to end and prints a remedy for each failure. These are the errors people hit most often.
/mcp shows servicenow-mcp as failed, or Claude Code says the server couldn't start.
Cause: Claude Code can't find the servicenow-mcp command. This is common with nvm, with a project-local install, or when Claude Code runs with a different PATH from your shell.
Fix: Run servicenow-mcp-setup doctor. If the server command check fails, remove the entry with claude mcp remove servicenow-mcp and register the server by absolute path instead:
claude mcp add --scope user servicenow-mcp -- "$(which node)" "$(npm root -g)/@onlyflows/servicenow-mcp/dist/index.js"Every tool call fails with “Table access was denied by policy.”
Cause: The profile has no grant for that table or tool. The other common cause: SN_ALLOWED_READ_TABLES or SN_ALLOWED_WRITE_TABLES is set in your environment while a profile file exists. Those variables only apply when there is no profile file.
Fix: Grant the table on the profile, then restart Claude Code so it starts a fresh server. servicenow-mcp-setup doctor reports both causes.
servicenow-mcp-setup grant --profile pdi --read incidentSetup says the instance “has no Table API at the expected path (HTTP 404)” or “did not respond before the timeout”.
Cause: The developer instance is hibernating, or the host name has a typo.
Fix: Wake the instance from developer.servicenow.com, wait until it loads in a browser, and run setup again. Enter just the host, such as dev12345.service-now.com.
Setup says the instance “rejected the credential (HTTP 401)”.
Cause: The username or password is wrong, the account is locked or waiting on a password reset, or the instance is enforcing ServiceNow's basic authentication restrictions for API calls (KB3096078).
Fix: Check the credential and the account's status. If the account is fine but API calls are refused, tick Web service access only on the user, give it the snc_basic_auth_api_access role, or switch the profile to OAuth.
Setup says the instance “accepted the credential but denied reading incident (HTTP 403)”.
Cause: The account signed in, but its ServiceNow roles don't allow reading incident.
Fix: Give the user a role that can read the tables you grant, such as itil. A table grant in the MCP server never widens what ServiceNow's ACLs allow.
Tool calls return an authentication error, although setup worked.
Cause: The server couldn't resolve the stored credential. An encrypted credential needs the SN_PROFILE_ENCRYPTION_KEY that setup wrote to ~/.servicenow-mcp/server.env. If that file is deleted or replaced, the credential can't be decrypted.
Fix: Run servicenow-mcp-setup doctor --profile pdi and follow the remedy it prints. Don't delete server.env; servicenow-mcp-setup --force regenerates the other identifiers but keeps the key. If the key is gone, re-enter the credential with servicenow-mcp-profile rotate --name pdi --field credential.
The assistant asks which instance to use, or a tool call is rejected because no profile was given.
Cause: Every tool call must name a profile, and there is no default. The model left it out.
Fix: Name it in the prompt (“on pdi, …”) or add the profile instruction described above, so Claude Code includes it on every call.
A grant you just added has no effect.
Cause: Claude Code started the server before you changed the profile, and the server reads the profile when it starts.
Fix: Restart Claude Code so it starts a fresh server.
Still stuck? Open an issue on GitHub with the doctor's output. It never prints a secret.
Related
ServiceNow MCP Server
The full tool list, the safety model, and how it compares with ServiceNow's official MCP Server.
Browse the OnlyFlows catalog
Download ServiceNow flows, subflows, actions, and scripts to explore and adapt with Claude Code.
Cursor setup guide
The same setup for Cursor, configured through mcp.json.
ServiceNow MCP without Now Assist
What ServiceNow's official MCP Server requires, and the alternatives.