Setup guide: Cursor

    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.

    Updated Tested with @onlyflows/servicenow-mcp 2.1.0About 20 minutes
    Quick Answer

    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 incident only 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, and sn_atf are never granted implicitly; you name them with --tools.
    • Your credential is checked against the instance, then stored encrypted in an owner-only ~/.servicenow-mcp directory. mcp.json never 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. 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. 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: itil covers incident, problem, and change. While you're trying things out, add snc_read_only as 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. 3

      Install the server

      Check that node --version prints v20 or newer, then install the package globally. A global install puts the servicenow-mcp command on your PATH, which is where your client looks for it.

      npm install -g @onlyflows/servicenow-mcp

      To try it without a global install, npx @onlyflows/servicenow-mcp@latest setup runs the same setup wizard.

    4. 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 (incident only), and keep the default of no writes:

      servicenow-mcp-setup

      Example 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 with ok.

      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 oauth instead and create an OAuth API endpoint client under System OAuth > Application Registry first.

    5. 5

      Add the server to Cursor's mcp.json

      Put the entry in ~/.cursor/mcp.json to use the server in every project, or in .cursor/mcp.json to scope it to one project. If the file already has an mcpServers object, add the servicenow-mcp entry 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 cursor

      The entry is only a command for Cursor to start. The server reads its credential from ~/.servicenow-mcp when it starts.

    6. 6

      Check the connection

      Run the doctor against your profile. It checks your Node version, that servicenow-mcp resolves 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 pdi

      Then 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_query with profile: "pdi" and table incident. Keep auto-run off for this server so you approve each ServiceNow call before it runs.

    7. 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. 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-run prints the result without writing it.

      Read another table

      servicenow-mcp-setup grant --profile pdi --read problem

      Query CIs and walk CMDB relationships

      servicenow-mcp-setup grant --profile pdi --read cmdb_ci --tools sn_query,sn_relationships

      Let the agent append work notes to incidents, and write nothing else

      servicenow-mcp-setup grant --profile pdi --write incident --tools sn_incident_add_work_note

      Preview allowing incident create and update

      servicenow-mcp-setup grant --profile pdi --write incident --dry-run

      A write grant without --tools allows sn_create and sn_update on that table. sn_delete, sn_batch, and sn_atf are never granted implicitly; you have to name them with --tools. Since 2.1, sn_create and sn_update write 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 incident

    Setup 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.

    FAQ