Getting Started

Client Setup Guide

Step-by-step setup for connecting NowAIKit to each supported AI client. Choose your client below and follow the configuration instructions to get up and running in minutes.

New to NowAIKit? Complete the Installation Guide first, then return here to configure your preferred AI client.

Prerequisites

All clients require the following before you begin:

✓

Node.js 20 or higher

Check with node --version. Download from nodejs.org.

✓

Server built and ready

Run npm install && npm run build in your NowAIKit directory.

✓

ServiceNow instance URL and credentials

Developer, sandbox, or production instance. You need the full URL and a service account.

Connect Your AI

Claude Code

Claude Code discovers MCP servers via the claude mcp add command. Run one of the commands below in your terminal to register NowAIKit.

Basic Auth

bash

$ claude mcp add servicenow \
  --command "node /absolute/path/to/nowaikit/dist/server.js" \
  --env SERVICENOW_INSTANCE_URL=https://yourinstance.service-now.com \
  --env SERVICENOW_AUTH_METHOD=basic \
  --env SERVICENOW_BASIC_USERNAME=your_username \
  --env SERVICENOW_BASIC_PASSWORD=your_password \
  --env WRITE_ENABLED=false

OAuth

The fast way: run nowaikit setup and choose OAuth. You sign in once, and the wizard detects an existing OAuth app, or provisions one for you, or falls back to username and password. On newer ServiceNow releases it creates a public client with PKCE, so there is no client secret to manage. After that, each user runs nowaikit auth login, which opens the browser to sign in with PKCE and no pasted code. On Zurich Patch 7 / Australia Patch 1 and later, CIMD lets you register one metadata URL with no per-client redirects. The manual environment variables below are the fallback.

bash

$ claude mcp add servicenow \
  --command "node /absolute/path/to/nowaikit/dist/server.js" \
  --env SERVICENOW_INSTANCE_URL=https://yourinstance.service-now.com \
  --env SERVICENOW_AUTH_METHOD=oauth \
  --env SERVICENOW_OAUTH_CLIENT_ID=your_client_id \
  --env SERVICENOW_OAUTH_CLIENT_SECRET=your_client_secret \
  --env SERVICENOW_OAUTH_USERNAME=your_username \
  --env SERVICENOW_OAUTH_PASSWORD=your_password \
  --env WRITE_ENABLED=false

Tip: Replace /absolute/path/to/nowaikit/dist/server.js with the actual absolute path on your system. Run pwd in the NowAIKit directory to find it.

Claude Desktop

Edit your Claude Desktop configuration file to add NowAIKit as an MCP server. The file location depends on your operating system.

Config file locations

OS	Path
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json`
Linux	`~/.config/Claude/claude_desktop_config.json`

Basic Auth Config

claude_desktop_config.json

{
  "mcpServers": {
    "servicenow": {
      "command": "node",
      "args": ["/absolute/path/to/nowaikit/dist/server.js"],
      "env": {
        "SERVICENOW_INSTANCE_URL": "https://yourinstance.service-now.com",
        "SERVICENOW_AUTH_METHOD":  "basic",
        "SERVICENOW_BASIC_USERNAME": "your_username",
        "SERVICENOW_BASIC_PASSWORD": "your_password",
        "WRITE_ENABLED":           "false",
        "MCP_TOOL_PACKAGE":        "service_desk"
      }
    }
  }
}

OAuth Config

The fast way: run nowaikit setup and choose OAuth. You sign in once, and the wizard detects an existing OAuth app, or provisions one for you, or falls back to username and password. On newer ServiceNow releases it creates a public client with PKCE, so there is no client secret to manage. After that, each user runs nowaikit auth login, which opens the browser to sign in with PKCE and no pasted code. On Zurich Patch 7 / Australia Patch 1 and later, CIMD lets you register one metadata URL with no per-client redirects. The manual config below is the fallback.

claude_desktop_config.json

{
  "mcpServers": {
    "servicenow": {
      "command": "node",
      "args": ["/absolute/path/to/nowaikit/dist/server.js"],
      "env": {
        "SERVICENOW_INSTANCE_URL":      "https://yourinstance.service-now.com",
        "SERVICENOW_AUTH_METHOD":        "oauth",
        "SERVICENOW_OAUTH_CLIENT_ID":    "your_client_id",
        "SERVICENOW_OAUTH_CLIENT_SECRET": "your_client_secret",
        "SERVICENOW_OAUTH_USERNAME":     "your_username",
        "SERVICENOW_OAUTH_PASSWORD":     "your_password",
        "WRITE_ENABLED":                 "false"
      }
    }
  }
}

Important: Restart Claude Desktop after saving the config file for changes to take effect.

OpenAI Codex

The OpenAI integration uses a Python wrapper that spawns the MCP server and translates tool schemas to OpenAI function definitions. This supports all current OpenAI function-calling models.

Setup

bash

$ cd clients/codex
$ pip install openai python-dotenv

Run

bash

$ python servicenow_openai_client.py

Make sure your .env file contains your OPENAI_API_KEY and ServiceNow credentials before running the client.

Google Gemini / Vertex AI

Connect NowAIKit to Google Gemini and Vertex AI. The integration converts tool schemas to Gemini function declarations, supporting the latest Gemini Pro and Flash models and all Gemini models with function calling.

Gemini API Setup

bash

$ cd clients/gemini
$ pip install google-generativeai python-dotenv

bash

$ python servicenow_gemini_client.py

Vertex AI Setup

For enterprise Vertex AI deployments, authenticate with Google Cloud first:

bash

$ gcloud auth application-default login

Google's free-tier Gemini models are a great option for teams looking to reduce AI costs while maintaining full ServiceNow tool coverage.

Cursor

Create or edit .cursor/mcp.json in your project root to register NowAIKit:

.cursor/mcp.json

{
  "mcpServers": {
    "servicenow": {
      "command": "node",
      "args": ["/absolute/path/to/nowaikit/dist/server.js"],
      "env": {
        "SERVICENOW_INSTANCE_URL":   "https://yourinstance.service-now.com",
        "SERVICENOW_AUTH_METHOD":     "basic",
        "SERVICENOW_BASIC_USERNAME": "your_username",
        "SERVICENOW_BASIC_PASSWORD": "your_password",
        "WRITE_ENABLED":             "false"
      }
    }
  }
}

Alternatively, add it globally via Cursor Settings → MCP → Add new global server.

VS Code

VS Code MCP support requires the GitHub Copilot extension or Claude for VS Code (Cline). Create or edit .vscode/mcp.json in your project root:

.vscode/mcp.json

{
  "servers": {
    "servicenow": {
      "type":    "stdio",
      "command": "node",
      "args": ["/absolute/path/to/nowaikit/dist/server.js"],
      "env": {
        "SERVICENOW_INSTANCE_URL":   "https://yourinstance.service-now.com",
        "SERVICENOW_AUTH_METHOD":     "basic",
        "SERVICENOW_BASIC_USERNAME": "your_username",
        "SERVICENOW_BASIC_PASSWORD": "your_password",
        "WRITE_ENABLED":             "false"
      }
    }
  }
}

Note: VS Code uses the "servers" key (not "mcpServers") and requires the "type": "stdio" property for each server entry.

Configuration

Reliability and safety

A few environment variables control how NowAIKit handles retries and timeouts. The defaults are sensible; set these only if you need to.

Variable	Default	What it does
`MAX_RETRIES`	`3`	Retries for failed reads. `0` means no retries (honored literally). Non-idempotent writes are never auto-retried when the response was lost, so a create can't be silently duplicated.
`RETRY_DELAY_MS`	`1000`	Base backoff between retries (exponential).
`REQUEST_TIMEOUT_MS`	`30000`	Per-request timeout in milliseconds.

Full list of settings: Configuration reference.

Support

Troubleshooting

Common issues and their solutions when setting up AI clients with NowAIKit:

Problem	Solution
Server won't start	Run `npm run build` first; check Node.js version is 20+ with `node --version`
Authentication failed	Verify instance URL has no trailing slash; confirm credentials are correct
No tools showing	Check MCP server logs; verify the path to `server.js` is absolute, not relative
Tool call errors	Check `WRITE_ENABLED`, `SCRIPTING_ENABLED`, and `ATF_ENABLED` flags match your intended permissions
OAuth token errors	Verify client ID and client secret; ensure the OAuth application is active in ServiceNow

Security tip: Never commit your .env file or config files containing credentials. Add them to .gitignore and use a dedicated service account with the minimum required ServiceNow roles.

Still stuck? Open a GitHub issue with your client name, error message, and Node.js version.