nowaikit installation guide

Complete setup instructions for connecting nowaikit to ServiceNow and any AI client.

Option A: Interactive Setup Wizard (Recommended)

Install and run the guided setup. No config file editing required.

$ npm install -g nowaikit
$ npx nowaikit@latest setup

nowaikit setup connects ServiceNow and configures your AI client. After that, each user signs in for themselves with nowaikit auth login, which opens the browser. The wizard walks you through:

Per-user sign-in

Once setup is done, each person signs in as themselves so their own ServiceNow identity is used. Run nowaikit auth login and it opens your browser to complete OAuth. Nothing to paste back into the terminal.

$ nowaikit auth login

Additional commands

$ nowaikit setup --add         # Add a second instance
$ nowaikit instances list      # List configured instances
$ nowaikit instances remove dev # Remove an instance
$ nowaikit auth login          # Per-user OAuth login
$ nowaikit auth whoami         # Show active ServiceNow user

Option B: Standalone Binary

Download a standalone binary, no Node.js required. Includes the full MCP server and setup CLI.

After downloading

# Make executable and move to PATH
$ chmod +x nowaikit-macos-arm64
$ sudo mv nowaikit-macos-arm64 /usr/local/bin/nowaikit
$ nowaikit setup

# Move to a folder in your PATH, then run:
> .\nowaikit-Setup.exe setup

Option C: Manual Setup

Step 1: Clone and build

$ git clone https://github.com/aartiq/nowaikit.git
$ cd nowaikit
$ npm install
$ npm run build

Step 2: Configure

$ cp .env.example .env

Edit .env:

SERVICENOW_INSTANCE_URL=https://yourcompany.service-now.com
SERVICENOW_AUTH_METHOD=basic
SERVICENOW_BASIC_USERNAME=your_username
SERVICENOW_BASIC_PASSWORD=your_password

Step 3: Point your AI client at the server

Config file locations by client:

System Prerequisites

ServiceNow OAuth 2.0 Setup

OAuth 2.0 is recommended for production.

1. In ServiceNow: navigate to System OAuth › Application Registry › New › Create an OAuth API endpoint for external clients
2. Set Name: nowaikit, Refresh Token Lifespan: 8640000, Access Token Lifespan: 1800
3. Enable Password Grant and Refresh Token grant types
4. Copy the Client ID and Client Secret

Enterprise Configuration

SSO / OIDC

Connect to Okta, Azure AD, Ping Identity, or any OIDC-compatible IdP.

Audit Logging

Every tool call is automatically logged. Configure with the following environment variables:

Org / Team Policy

Deploy nowaikit.org.json via MDM/GPO to enforce organisation-wide configuration policies.

HTTP API Server

Use nowaikit serve to expose all tools as a REST API.

Transport Configuration

NowAIKit v4.0.0 supports three transport modes: stdio (default, for MCP clients), SSE (Server-Sent Events for web integrations), and Streamable HTTP (for modern HTTP-based agents).

Stdio (Default)

Stdio is the standard MCP transport. It communicates over standard input/output and is used by Claude Desktop, Cursor, VS Code extensions, and most MCP-compatible clients.

• No configuration needed, just run npx nowaikit@latest
• Fastest transport with the lowest latency
• No network ports opened
• One client per process

{
  "mcpServers": {
    "nowaikit": {
      "command": "npx",
      "args": ["-y", "nowaikit"],
      "env": {
        "SERVICENOW_INSTANCE_URL": "https://yourinstance.service-now.com",
        "SERVICENOW_AUTH_METHOD": "basic",
        "SERVICENOW_BASIC_USERNAME": "admin",
        "SERVICENOW_BASIC_PASSWORD": "your_password"
      }
    }
  }
}

SSE Transport

SSE (Server-Sent Events) is ideal for web integrations, browser-based clients, and scenarios where you need a persistent HTTP connection with real-time streaming.

$ TRANSPORT=sse npx nowaikit@latest

SSE Configuration

SSE Endpoints

# Test SSE connection
$ curl -N http://localhost:3000/sse

# Send a message
$ curl -X POST http://localhost:3000/messages \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

Streamable HTTP Transport

Streamable HTTP is the modern MCP transport, preferred for new integrations. It uses a single multiplexed endpoint and supports both request-response and streaming patterns over standard HTTP.

$ TRANSPORT=http npx nowaikit@latest

Uses the same PORT, HOST, and CORS_ORIGIN variables as SSE.

HTTP Endpoint

$ curl -X POST http://localhost:3000/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

Transport Authentication

For SSE and Streamable HTTP transports, you can optionally secure access with an API key.

NOWAIKIT_API_KEY=your-secret-api-key

When NOWAIKIT_API_KEY is set, all requests must include an Authorization header:

$ curl -X POST http://localhost:3000/mcp \
  -H 'Authorization: Bearer your-secret-api-key' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

• The health endpoint at GET /health is always unauthenticated
• When no API key is set, all endpoints are open (suitable for local development)
• Stdio transport does not use API key authentication (process-level isolation instead)

REST API (SSE/HTTP only)

When running in SSE or HTTP transport mode, a REST API is available at /api/* for direct tool invocation outside of the MCP protocol.

# List all tools
$ curl http://localhost:3000/api/tools

# Execute a tool
$ curl -X POST http://localhost:3000/api/tool \
  -H 'Content-Type: application/json' \
  -d '{"name":"get_incident","arguments":{"number_or_sysid":"INC0010001"}}'

A2A Protocol (SSE/HTTP only)

NowAIKit exposes an Agent-to-Agent (A2A) interface when running in SSE or HTTP transport mode.

# Discover the agent
$ curl http://localhost:3000/.well-known/agent.json

# Send a task
$ curl -X POST http://localhost:3000/a2a/tasks/send \
  -H 'Content-Type: application/json' \
  -d '{"task":{"message":"List my open P1 incidents"}}'

Dashboard

When running in SSE or HTTP transport mode, NowAIKit serves a web dashboard at the root path (/).

• Tool explorer: browse and search all 500+ tools
• Search: filter tools by name, category, or module
• Instance info: see which ServiceNow instance is connected

# Start with SSE transport and open dashboard
$ TRANSPORT=sse npx nowaikit@latest
# Then open http://localhost:3000 in your browser

Transport Environment Variables

Example Configurations

Stdio (default, for MCP clients)

# Stdio transport (default — no TRANSPORT variable needed)
SERVICENOW_INSTANCE_URL=https://yourinstance.service-now.com
SERVICENOW_AUTH_METHOD=basic
SERVICENOW_BASIC_USERNAME=admin
SERVICENOW_BASIC_PASSWORD=your_password

SSE (web integrations)

TRANSPORT=sse
PORT=3000
HOST=0.0.0.0
CORS_ORIGIN=https://myapp.example.com
NOWAIKIT_API_KEY=my-secret-key-here

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=svc_account
SERVICENOW_OAUTH_PASSWORD=svc_password

WRITE_ENABLED=true
MCP_TOOL_PACKAGE=full

Streamable HTTP (modern agents)

TRANSPORT=http
PORT=8080
HOST=127.0.0.1
CORS_ORIGIN=*
NOWAIKIT_API_KEY=my-secret-key-here

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=svc_account
SERVICENOW_OAUTH_PASSWORD=svc_password

WRITE_ENABLED=true
MCP_TOOL_PACKAGE=full

Quick Recipes

Copy-paste examples for common v4.0.0 workflows.

Start HTTP server and call a tool in one go

# Terminal 1 — start the server
$ TRANSPORT=http PORT=3000 NOWAIKIT_API_KEY=my-key npx nowaikit@latest

# Terminal 2 — call a tool via REST API
$ curl -X POST http://localhost:3000/api/tool \
  -H 'Authorization: Bearer my-key' \
  -H 'Content-Type: application/json' \
  -d '{"name":"get_incident","arguments":{"number_or_sysid":"INC0010001"}}'

Discover a custom table via REST API

# Use discover_table to auto-generate CRUD tools for any table
$ curl -X POST http://localhost:3000/api/tool \
  -H "Authorization: Bearer $NOWAIKIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"discover_table","arguments":{"table_name":"u_custom_app"}}'

A2A agent-to-agent task

# 1. Discover the agent
$ curl http://localhost:3000/.well-known/agent.json

# 2. Send a task via A2A
$ curl -X POST http://localhost:3000/a2a/tasks/send \
  -H "Content-Type: application/json" \
  -d '{"task":{"message":"Create a P2 incident for slow VPN performance"}}'

SSE transport with curl

# Start SSE server
$ TRANSPORT=sse PORT=3000 npx nowaikit@latest

# Connect to SSE stream (long-lived connection)
$ curl -N http://localhost:3000/sse

# Send an MCP message
$ curl -X POST http://localhost:3000/messages \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

Verification and Testing

Using the wizard

After setup, restart your AI client and test with a natural language prompt:

"List my 5 most recent open incidents"

Manual verification

1. Restart your AI client
2. Ask: "Get the schema for the incident table"
3. Ask: "Show me 5 open P1 incidents"
4. Ask: "Create a test incident". This should fail if WRITE_ENABLED=false

Troubleshooting

Common issues and their solutions:

Environment Variables Reference

ServiceNow Connection

Basic Auth

OAuth 2.0

Permission Tiers

Tool Packaging

Multi-Instance

Transport & Server

See the Transport Configuration section below for full setup details, curl examples, and .env templates for each transport mode.

Audit Logging

SSO / OIDC