Setup guide: Claude Code

    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.

    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, 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 claude command 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 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. 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. 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.

      If the claude command is on your PATH, setup then offers to register the server with Claude Code. Answer y.

      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

      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 user makes 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-mcp

      Check that it's registered

      claude mcp list

      Or share it with a project: check in .mcp.json at the project root

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

      The .mcp.json entry only tells Claude Code what to start, never a credential. Each teammate runs servicenow-mcp-setup with their own account.

    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 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_query with profile: "pdi" and table incident. Each call also writes one audit line to the server log Claude Code keeps, with no credentials or record contents in it.

    7. 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.md file in your project:

      CLAUDE.md

      ServiceNow: use the servicenow-mcp profile "pdi". 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.

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

    FAQ