Connect an AI client to ServiceNow locally, verify the web dashboard, then publish only the HTTP service you intend to reach
NowAIKit is a self-hostable, source-available ServiceNow integration that can run as an MCP server, direct command-line tool, or local web service. In this guide, we install the official npm package on Node.js 20 or newer, use its setup wizard, verify an MCP client configuration, and start the local web dashboard. Once the application works locally, we configure a Localtonet HTTP tunnel so the dashboard can be reached remotely without inbound router port forwarding, firewall changes, a public IP address, or VPN setup. We also explain the security boundary between local MCP stdio transport, NowAIKit's network transports, and an HTTP tunnel.
📋 What's in this guide
How the NowAIKit and Localtonet architecture works
NowAIKit connects an AI client to a ServiceNow instance. The AI client can ask NowAIKit to query or operate on ServiceNow through the tools that the current configuration permits. The official project describes more than 500 tools across areas including ITSM, ITOM, CMDB, HRSD, CSM, Flow Designer, scripting, portals, reporting, and application development. It also supports dynamic discovery of tables and fields in the connected instance.
The safest way to approach this deployment is as two separate phases. First, install and validate NowAIKit entirely on the local machine. Confirm that the package starts, the setup wizard can reach ServiceNow, and the selected AI client recognizes the MCP server. Second, start the optional web dashboard and expose that specific local HTTP listener with Localtonet.
Localtonet does not replace NowAIKit's ServiceNow authentication, permission tiers, MCP configuration, or application-level authorization. Our client creates an outbound connection from the device to a Localtonet relay server. An HTTP tunnel then maps an assigned public HTTPS address to the local IP address and port where the NowAIKit web service is listening. The tunnel remains available only while the selected Localtonet client is connected and the tunnel is running.
npx nowaikit web command starts a local dashboard. Its displayed listening address supplies the IP address and port required for local testing and tunnel configuration.
Do not confuse the dashboard with an MCP network transport
The dashboard, stdio MCP server, SSE transport, and Streamable HTTP transport are related features, but they are not interchangeable. This guide exposes the local web dashboard because it presents a conventional HTTP service that can be tested in a browser. The normal stdio MCP configuration launches NowAIKit as a child process and has no TCP port for Localtonet to forward.
NowAIKit also documents SSE and Streamable HTTP transports for network-based integrations. Those modes have their own endpoints, client compatibility requirements, authentication considerations, and startup configuration. Do not assume that publishing the web dashboard automatically gives a remote MCP client a usable Streamable HTTP endpoint. Configure a network MCP transport only when the intended AI client explicitly supports it and after checking the current NowAIKit documentation for its complete endpoint and bearer-token requirements.
The approved project evidence does not establish a fixed bind address or port for npx nowaikit web. Record the exact URL printed when the command starts. Do not copy an unrelated default from an SSE, Streamable HTTP, or REST API example.
Prerequisites for self-hosting NowAIKit
The npm installation path requires Node.js 20.0.0 or newer. The current documentation also lists npm 9 or newer. A normal Node.js installation includes npm, but both versions should be checked before installing the package. You also need a ServiceNow instance, its URL, an appropriate identity, and a compatible AI client if you intend to use MCP mode.
| Requirement | What you need | How to check or prepare it |
|---|---|---|
| Node.js | Version 20.0.0 or newer | Run node --version and upgrade Node.js if the reported major version is below 20. |
| npm | Version 9 or newer | Run npm --version. npm is normally included with Node.js. |
| ServiceNow | A developer, sandbox, or production instance | Have the instance URL and an identity whose ServiceNow roles match the operations you plan to allow. |
| Authentication | Basic authentication or a supported OAuth configuration | Prefer OAuth for production. Creating the required OAuth application in ServiceNow requires appropriate administrative access. |
| AI client | An MCP-compatible client for MCP mode | The setup wizard can configure documented clients such as Claude Desktop or Cursor. Exact support can change with project releases. |
| Localtonet client | A connected client on the NowAIKit host or another device that can reach it | Install and run our client, then select its device-specific authentication token when creating the tunnel. |
Check Node.js and npm
node --version
npm --versionStop here if Node.js is older than version 20. Installing NowAIKit with an unsupported runtime can lead to installation failures, syntax errors, or behavior that differs from the official release. Upgrade Node.js through the installation method appropriate for your operating system, then open a new terminal and run both version checks again.
Choose the ServiceNow environment deliberately
A developer or sandbox instance is the best starting point for validating connectivity, tool visibility, and permission behavior. NowAIKit starts in a read-only mode, but ServiceNow credentials still provide access to instance data. Testing away from production reduces the impact of configuration errors and lets administrators review roles before enabling any additional capability tier.
If you do not already have an instance, the project documentation points readers to a ServiceNow Personal Developer Instance. Availability and enrollment are controlled by ServiceNow. Regardless of instance type, use a dedicated identity with the minimum roles required for the intended queries or actions rather than reusing a broadly privileged administrator account for routine operation.
Never place ServiceNow passwords, OAuth client secrets, Localtonet device tokens, bearer tokens, or private endpoints in a public repository, screenshot, support post, or shared configuration example. Use the setup wizard, environment variables, or an appropriate secrets-management mechanism. Redact terminal output before sharing it.
Install NowAIKit with Node.js and npm
The recommended Node.js workflow installs the nowaikit npm package globally and then runs the interactive setup wizard. The project states that its official distribution is provided through the nowaikit npm package or the NowAIKit website. Do not rely on an unverified downloadable archive or a similarly named repository.
Install the official npm package globally
Run npm install -g nowaikit in a terminal. A global installation makes the nowaikit command available through the executable path configured by npm.
Launch the current setup wizard
Run npx nowaikit@latest setup. The wizard gathers the ServiceNow connection settings, tests connectivity, lets you choose permissions and a tool package, and can write the selected AI client's configuration.
npm install -g nowaikit
npx nowaikit@latest setup
Using @latest asks npm to execute the current published package release. In a controlled environment, review and test a release before rolling it out broadly. A version change can affect supported clients, configuration fields, transports, or available tools even when the basic setup commands remain the same.
Verify that the command is available
nowaikit --version
A successful response confirms that the executable can be found. The exact version number will depend on the package release installed at the time, so this guide does not prescribe a version string. If the shell reports that the command cannot be found, close and reopen the terminal first. If that does not help, inspect the npm global executable path and ensure it is included in the current user's PATH.
When a global npm installation is not appropriate
NowAIKit also documents running the package through npx, using platform-specific standalone binaries, or cloning and building the source. This article uses the npm workflow because it is the documented installation path in the project README and aligns with the Node.js installation intent.
Running through npx -y nowaikit can be useful in an MCP client configuration because it does not depend on the client resolving a globally installed executable in exactly the same way as an interactive shell. A source build is more appropriate for contributors or administrators who need to inspect and build a checked-out revision. It adds Git, dependency installation, build, update, and source-integrity responsibilities, so it is not required for the normal setup shown here.
Configure ServiceNow and an MCP client
The interactive wizard is the preferred configuration path. It reduces manual JSON editing and tests the ServiceNow connection before completing the client setup. Run it from the same operating-system account that uses the AI client so that configuration file permissions and paths match the intended user.
Enter the ServiceNow instance
Supply the URL of the intended ServiceNow instance and select the authentication method offered by the current wizard. Check the hostname carefully so a development configuration is not accidentally pointed at production.
Provide the authentication details
Enter the requested username and password or OAuth details. Use a dedicated, least-privileged identity and avoid saving secrets in shell history, source control, or shared notes.
Let the wizard test connectivity
The wizard verifies that NowAIKit can reach the instance and authenticate. Resolve URL, network, certificate, credential, and ServiceNow role problems before proceeding.
Select a tool package and permissions
Choose the package appropriate for the user's role and keep the default read-only posture until additional operations have been reviewed. Tool visibility and ServiceNow authorization are separate controls, and both should be restrictive.
Install the configuration into the AI client
Select the target offered by the wizard, such as Claude Desktop, Cursor, both, or environment-only configuration. After completion, fully restart the AI client so it reloads its MCP configuration.
Per-user OAuth sign-in
In the documented per-user workflow, each person signs in with their own ServiceNow identity after setup. The following command opens a browser to complete the OAuth flow:
nowaikit auth loginThe active identity can then be checked with:
nowaikit auth whoamiPer-user identity is preferable to a shared account because ServiceNow authorization and audit records can correspond to the person performing the operation. The exact OAuth application, redirect, licensing, and organizational identity requirements should be reviewed against the current NowAIKit and ServiceNow documentation before production deployment.
Manual MCP configuration
If the wizard cannot edit the selected client, the documented stdio configuration launches npx with the NowAIKit package. The conceptual structure is shown below. Replace placeholders only in a private configuration file, and follow the exact file path and schema expected by the specific client version.
{
"mcpServers": {
"nowaikit": {
"command": "npx",
"args": ["-y", "nowaikit"],
"env": {
"SERVICENOW_INSTANCE_URL": "https://your-instance.example",
"SERVICENOW_AUTH_METHOD": "basic",
"SERVICENOW_BASIC_USERNAME": "your-username",
"SERVICENOW_BASIC_PASSWORD": "use-a-secret-value"
}
}
}
}This is a stdio configuration. The AI client starts NowAIKit and exchanges MCP messages through the process streams. No Localtonet tunnel is required for that local relationship. Also note that storing a password directly in JSON can expose it to local backups, synchronization tools, other users, or accidental commits. Use OAuth or the secret-handling method supported by your environment when possible.
Documented configuration paths include ~/Library/Application Support/Claude/claude_desktop_config.json for Claude Desktop on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows, ~/.config/Claude/claude_desktop_config.json on Linux, and ~/.cursor/mcp.json for Cursor. Client releases can change file locations or schemas, so prefer the setup wizard and confirm the current client's requirements before editing.
Verify NowAIKit before exposing anything
Remote-access troubleshooting becomes much simpler when local operation has already been proven. Verify the installation, ServiceNow connection, AI client process, and permission posture before starting the web dashboard or creating a tunnel.
Confirm the installed command
Run nowaikit --version. A version response proves that the shell can locate and execute the package.
Confirm the ServiceNow identity
If using the documented per-user authentication flow, run nowaikit auth whoami and verify that it reports the intended user and instance rather than a shared or production identity selected by mistake.
Restart and inspect the AI client
Fully exit and reopen the client after setup. Confirm that NowAIKit appears as an available MCP server or tool provider according to the client's interface.
Perform a harmless read-only test
Ask for a small, non-sensitive read operation that the connected ServiceNow identity is allowed to perform. Avoid write, scripting, CMDB, or agentic tests until the result, role mapping, and target instance have been reviewed.
A successful read test proves several layers at once: the AI client can launch the MCP process, NowAIKit can authenticate to ServiceNow, the selected tools are visible, and the ServiceNow identity has at least the required read permission. A failed test does not necessarily mean the package is broken. It can indicate a stale AI client process, invalid JSON, a missing executable path, an incorrect instance URL, an expired OAuth session, insufficient ServiceNow roles, or a network policy blocking the instance.
Read access can still reveal incidents, user records, configuration data, customer information, or other sensitive content. Limit the ServiceNow identity, select a role-appropriate tool package, test with non-sensitive requests, and review what the AI client records or sends to its model provider.
Start and verify the local NowAIKit web dashboard
Once MCP operation is known to work, start the documented local dashboard in a separate terminal:
npx nowaikit webKeep this terminal open. Read the startup output and record the complete local URL it displays, including the scheme, hostname or IP address, and port. That output is the authoritative value for this process. The dashboard command's bind address and port are not fixed by the evidence available for this article, so we do not provide a guessed example.
Verify the dashboard from the host
Open the exact displayed URL in a browser on the NowAIKit host. Confirm that the page loads and that its expected interface is present. If the terminal reports a startup error or the local browser cannot connect, do not create a tunnel yet. Resolve the local application problem first.
Where an approved internal policy permits command-line testing, you can pass the exact displayed URL to an HTTP client such as curl. Do not substitute a guessed port:
curl "PASTE_THE_EXACT_LOCAL_URL_SHOWN_BY_NOWAIKIT_HERE"The response may be HTML, a redirect, or another application-defined result. The important check is that the local TCP connection succeeds and the NowAIKit process logs the request. If the displayed URL uses a hostname that Localtonet cannot resolve in its target field, use the corresponding local IP address only after confirming that the application is actually listening on it.
Keep the different web commands separate
The project also documents nowaikit serve for a REST API server and environment-selected SSE or Streamable HTTP transports. Those modes expose endpoints intended for integrations, not merely the dashboard workflow documented here. Their access controls, endpoint paths, and compatible clients require separate validation. Starting one command and tunneling to it does not guarantee that a client designed for another transport will work.
| Mode | Local behavior | Role in this guide |
|---|---|---|
| stdio MCP | Uses process input and output with no network port | Used by a locally configured MCP client; not tunneled |
| Web dashboard | Starts a browser-accessible local web service | The HTTP service exposed after local verification |
| SSE | Uses HTTP endpoints and a persistent event stream | Outside this dashboard-focused workflow |
| Streamable HTTP | Uses an MCP network endpoint for request-response and streaming patterns | Requires a compatible remote MCP client and separate configuration review |
| REST API server | Provides web and API endpoints documented by NowAIKit | Not assumed to be equivalent to npx nowaikit web |
Expose the verified dashboard with a Localtonet HTTP tunnel
Configure Localtonet only after the dashboard loads locally. Our client should run on the NowAIKit host whenever practical. It may instead run on another device that can reach the dashboard over the local network, but in that case the NowAIKit service must listen on an address reachable from that device and local network policy must permit the connection.
An HTTP tunnel is the natural choice for the browser dashboard. Localtonet's HTTP Process Type can use a random subdomain, a supported custom subdomain, or a custom domain. Each serves the target through a public HTTPS address. Availability can vary by plan or current dashboard options, and custom-domain DNS requirements should be checked in the current Localtonet documentation before changing DNS.
Install and run the Localtonet client
Run our client on the NowAIKit host or on a device that can reach the local dashboard. The client establishes an outbound connection, so this workflow does not require inbound router port forwarding, a public IP address, firewall changes, or VPN setup.
Authenticate and select the intended device
Use the device-specific authentication token associated with the client that will carry the traffic. Treat the token as a secret and never paste it into documentation, application configuration, or a public terminal recording.
Select an available relay server
Choose a server or region currently offered in the Localtonet dashboard. Available values can vary, so this guide does not hardcode a server code or geographic location.
Create an HTTP tunnel to the local dashboard
Choose an HTTP tunnel and enter the local IP address and port shown by npx nowaikit web. Select the desired Process Type from the options currently available to the account. Do not enter the ServiceNow hostname, an MCP stdio command, or a port copied from an unrelated transport example.
Start the tunnel
Creating a tunnel does not start it. Press the Start button and wait for the selected client and tunnel to show that they are connected. The dashboard must remain running at the configured local target.
Test the assigned public address
Open the assigned public HTTPS URL from an external network or intended remote device. Confirm that the expected NowAIKit dashboard loads, then stop or delete the tunnel when remote access is no longer required.
For current product controls and field names, consult the Localtonet HTTP tunnel documentation. The exact dashboard choices, relay servers, and plan availability can change, so current values in the authenticated dashboard take precedence over examples.
How to choose the local target
If Localtonet runs on the same machine as NowAIKit and the dashboard reports a loopback address, target that displayed local address and port. If Localtonet runs on a different device, a loopback address on the NowAIKit host will not be reachable from it. In that topology, the application needs a LAN-reachable bind address supported by NowAIKit, and the Localtonet target must use the host's reachable private address.
This guide does not prescribe an undocumented bind flag for npx nowaikit web. If the command only binds to loopback, install the Localtonet client on the same host or check the current NowAIKit documentation for an officially supported binding option. Do not guess flags or expose a development listener by changing operating-system networking controls without understanding the effect.
The public URL works only while the selected Localtonet client is connected, the tunnel is started, and the NowAIKit dashboard is listening at the configured local target. A tunnel can be connected while its target application is stopped, which results in a public endpoint that cannot deliver the dashboard.
Security controls for remote NowAIKit access
A public URL changes the dashboard's exposure boundary. A service that was previously reachable only from the host may now receive requests from the public internet. HTTPS at the tunnel edge protects transport to the public endpoint, but it does not decide who should be allowed to use the application or which ServiceNow operations they may perform.
The supplied evidence does not establish the authentication behavior of the dashboard started by npx nowaikit web. Do not assume it requires a login or bearer token. Before creating a public tunnel, verify the current NowAIKit behavior and add appropriate access controls. If you cannot establish that unauthorized visitors are blocked, keep the dashboard local.
Use layered authorization
Apply least privilege at every layer. The ServiceNow identity should have only the roles required for its tasks. NowAIKit should load an appropriate tool package and remain read-only unless a documented business need justifies additional capabilities. Any application authentication supported by the selected web mode should be enabled and tested. Organizational access restrictions should be applied according to current Localtonet capabilities and the account's available options rather than assumed from this guide.
Enable capabilities incrementally
NowAIKit documents separate permission tiers beyond the default read level. Write operations, CMDB changes, scripting, and agentic capabilities require explicit opt-in. These controls reduce accidental access, but enabling a capability does not grant missing ServiceNow roles and does not make every operation appropriate.
Introduce one capability category at a time in a non-production instance. Test expected operations, denied operations, audit visibility, and error behavior. Scripting and autonomous features deserve especially careful review because their potential effect is broader than reading a record.
Protect configuration and logs
Configuration files can contain instance URLs, usernames, passwords, OAuth material, or information about local paths. Restrict filesystem permissions and exclude those files from source control. Terminal logs and screenshots can also disclose public tunnel URLs, account names, instance names, or tokens.
Review what NowAIKit, the AI client, ServiceNow, and any model provider record. A read-only query can still place sensitive ServiceNow data into local logs, AI conversation history, telemetry, or a remote model context. Apply your organization's data-classification, retention, and approved-model policies before allowing real records to be processed.
Limit the duration of exposure
Start the tunnel for a defined task and stop it afterward. If the access requirement is permanent, treat the deployment as an internet-facing service with ownership, patching, monitoring, incident response, credential rotation, and periodic access review. Do not use an indefinitely running development dashboard as a substitute for a reviewed production architecture.
Routine operation and troubleshooting
Recommended startup order
Start dependencies from the inside out. First confirm that the ServiceNow instance is reachable and that the required identity is valid. Next start NowAIKit and verify the dashboard locally. Then start the Localtonet client and the existing HTTP tunnel. Finally, test the public URL.
This order isolates faults. If the dashboard fails locally, the issue is in the application, runtime, authentication, or host. If it works locally but not through Localtonet, compare the tunnel target with the exact displayed listener address and confirm that the selected device and tunnel are connected.
Recommended shutdown order
Stop the Localtonet tunnel first so no new remote requests can arrive. Then stop the NowAIKit web process. If the device no longer needs any Localtonet tunnel, stop the client as well. Delete obsolete tunnels and remove stale credentials according to your organization's lifecycle policy.
Useful NowAIKit account and instance commands
nowaikit instances list
nowaikit setup --add
nowaikit instances remove dev
nowaikit auth login
nowaikit auth whoami
The first command lists configured instances. The setup command with --add adds another instance, while the removal example removes an instance named dev. Confirm the actual configured name before removing anything. The authentication commands begin per-user sign-in and display the active ServiceNow identity.
| Symptom | Likely layer | What to check |
|---|---|---|
node or npm is not found |
Runtime installation | Install Node.js 20 or newer, reopen the terminal, and verify the executable path. |
nowaikit is not found after installation |
npm executable path | Open a new shell and confirm that npm's global executable directory is in PATH. |
| The setup wizard cannot connect to ServiceNow | URL, network, or authentication | Verify the instance hostname, credentials or OAuth session, outbound connectivity, and account status. |
| The AI client does not show NowAIKit | MCP client configuration | Restart the client, validate its JSON, verify its configuration path, and confirm it can resolve npx. |
| A read query is denied | ServiceNow authorization | Confirm the active identity, selected instance, tool package, and ServiceNow roles needed for the requested data. |
| The dashboard command starts but the page does not load locally | Local web listener | Use the exact URL printed by the process, inspect startup errors, and check whether another process is using the selected port. |
| The dashboard works locally but not through the tunnel | Localtonet target or lifecycle | Confirm the target IP and port, selected device, relay selection, client connection, tunnel status, and dashboard process. |
| The public page loads but MCP clients cannot connect | Transport mismatch | Do not treat a dashboard URL as a Streamable HTTP or SSE endpoint. Configure the transport required by the client using current NowAIKit instructions. |
| The public endpoint returns an unexpected service | Incorrect port | Stop the tunnel and compare its target with the URL printed by npx nowaikit web. |
Separate application failures from tunnel failures
Test the same target in three stages. First access it on the host using the exact displayed URL. Second, if Localtonet is on another device, access the target from that device over the LAN. Third, test the assigned public URL. The first failed stage identifies the layer that needs attention.
Avoid changing multiple variables simultaneously. Do not switch authentication methods, enable write capabilities, alter the bind address, and create a new tunnel in one troubleshooting attempt. Make one controlled change, repeat the smallest relevant test, and record the result.
Updating safely
Before updating NowAIKit, record the working package version and back up configuration through an approved secure process. Review release information, test the new package against a non-production ServiceNow instance, and confirm that the AI client, authentication flow, dashboard, and tunnel target still behave as expected.
If an update changes the dashboard's listening port, the Localtonet tunnel must be updated to match. If it changes the client configuration schema or executable behavior, regenerate or review the MCP configuration rather than assuming the old file remains valid.
Frequently asked questions
What version of Node.js does NowAIKit require?
The documented npm installation requires Node.js 20.0.0 or newer. The current documentation also lists npm 9 or newer. Check both with node --version and npm --version before installation.
What are the official installation commands?
For the Node.js workflow, install the package with npm install -g nowaikit and run the current setup wizard with npx nowaikit@latest setup. The project advises obtaining NowAIKit through its official npm package or website rather than an unverified archive.
Does the normal MCP configuration need a Localtonet tunnel?
No. The default MCP mode uses stdio, so the AI client launches NowAIKit locally and communicates through the process streams. This guide uses Localtonet for the separate browser-accessible web dashboard, not for the local stdio connection.
Which port should I enter in the Localtonet HTTP tunnel?
Use the port shown by npx nowaikit web when it starts. The evidence available for this guide does not establish a fixed dashboard port. Do not copy the default associated with another NowAIKit transport or server mode.
Is NowAIKit read-only?
It is read-only by default. Write, CMDB, scripting, and agentic capabilities require explicit opt-in. ServiceNow authorization still applies, so enabling a NowAIKit capability does not grant roles that the connected ServiceNow identity does not have.
Does a public Localtonet URL automatically secure the dashboard?
No. The public HTTPS address provides connectivity to the local HTTP target, but application authentication and ServiceNow authorization remain separate responsibilities. Because the dashboard authentication behavior is not established by the supplied evidence, verify it before exposure and keep the service local if unauthorized users cannot be reliably blocked.
Can the Localtonet client run on a different machine?
Yes, if that machine can reach the NowAIKit dashboard's local IP address and port. A service bound only to loopback is not reachable from another device. Installing our client on the NowAIKit host is usually the simplest approach for a loopback-only dashboard.
Will the public URL remain available after I close the terminal?
The endpoint requires the NowAIKit web process, the selected Localtonet client, and the tunnel to remain running. Closing the terminal may stop the dashboard process. Stopping the tunnel or disconnecting the client also ends public access.
Connect your verified NowAIKit dashboard with Localtonet
Install and test NowAIKit locally first, record the dashboard address it actually displays, and then create a Localtonet HTTP tunnel to that verified target. Keep the ServiceNow identity least-privileged, confirm application authentication, and stop the tunnel whenever remote access is no longer needed.
Get Started Free →
