How to connect Cursor to a ServiceNow developer instance
Install the OnlyFlows ServiceNow MCP server, connect it to your personal developer instance (PDI) with read-only access, add it to Cursor's mcp.json, 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 and keep the default read-only grant. Add "servicenow-mcp": { "command": "servicenow-mcp", "args": [] } under mcpServers in ~/.cursor/mcp.json, check that Cursor's MCP settings list the server, and ask the agent: “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.
- Cursor, with access to Agent mode.
- 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.mcp.jsonnever holds it, so a project config is safe to commit. - 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.Cursor is configured by a file, which you'll add in the next step. If setup offers to register Claude Code or Codex and you don't use them, answer
n.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
Add the server to Cursor's mcp.json
Put the entry in
~/.cursor/mcp.jsonto use the server in every project, or in.cursor/mcp.jsonto scope it to one project. If the file already has anmcpServersobject, add theservicenow-mcpentry inside it.~/.cursor/mcp.json
{ "mcpServers": { "servicenow-mcp": { "command": "servicenow-mcp", "args": [] } } }Or print the entry and the file locations
servicenow-mcp-setup client --client cursorThe entry is only a command for Cursor to start. The server reads its credential from
~/.servicenow-mcpwhen it starts. - 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 open Cursor's settings, confirm servicenow-mcp is listed under MCP with its tools, and ask the agent:
On pdi, show me the five most recent incidents with their number and short description.The agent should call
sn_querywithprofile: "pdi"and tableincident. Keep auto-run off for this server so you approve each ServiceNow call before it runs. - 7
Tell Cursor 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 project rule that always applies:
.cursor/rules/servicenow.mdc
--- description: ServiceNow MCP profile alwaysApply: true --- Use the servicenow-mcp profile "pdi" for ServiceNow tool calls. 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.After a grant, restart Cursor, or turn the server off and on again in Cursor's MCP settings, so it starts a fresh server that reads the updated profile.
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.
Cursor shows the server with an error status or no tools.
Cause: Cursor can't start the servicenow-mcp command. Opened from the Dock or Start menu, Cursor may not have the PATH your shell has, which is common with nvm or Homebrew installs of Node. A JSON syntax error in mcp.json has the same effect.
Fix: Check that the file is valid JSON, then run servicenow-mcp-setup doctor. If the server command check fails, use absolute paths in the entry. which node prints the first path, and npm root -g prints the folder that contains the package:
{
"mcpServers": {
"servicenow-mcp": {
"command": "/absolute/path/to/node",
"args": ["/absolute/path/to/node_modules/@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 Cursor 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 Cursor includes it on every call.
A grant you just added has no effect.
Cause: Cursor started the server before you changed the profile, and the server reads the profile when it starts.
Fix: Restart Cursor 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 in Cursor.
Claude Code setup guide
The same setup for Claude Code, registered with one command.
ServiceNow MCP without Now Assist
What ServiceNow's official MCP Server requires, and the alternatives.