SDK Quickstart

The NowAIKit SDK is a TypeScript/JavaScript library for programmatic ServiceNow access. Unlike the MCP integration (which loads ~88K tokens of tool schemas for AI conversations), the SDK provides zero token overhead — direct function calls that compile to clean REST requests. Import it, call a method, get results. v2.0.0 adds the A2A client, OAuth PKCE authentication, SSE streaming, schema caching, a Now Assist client, and Fluent types.

When to Use SDK vs MCP

Both the SDK and MCP connect to the same ServiceNow APIs with the same 450+ operations. The difference is how you invoke them.

Use the SDK when you need:

• Automation & CI/CD scripts — Deploy changes, run health checks, or sync data as part of a pipeline. No AI layer needed.
• Token-sensitive scenarios — When every token counts (large context windows, cost optimization), the SDK adds zero overhead.
• Backend services — Build microservices, webhooks, or scheduled jobs that interact with ServiceNow programmatically.
• Custom integrations — Connect ServiceNow to other systems (Slack bots, monitoring tools, internal dashboards) with typed function calls.
• Batch processing — Process thousands of records efficiently with direct API calls and built-in retry logic.

Use MCP when you need:

• Interactive AI conversations — Let Claude, GPT, or Gemini query and modify ServiceNow through natural language.
• Natural language queries — "Show me all P1 incidents from last week" translates to the right API call automatically.
• Tool chaining — AI agents that decide which tools to call based on context and chain operations together.
• Ad-hoc exploration — Investigate incidents, explore CMDB relationships, or debug issues conversationally.

Installation

Install the SDK from npm or use bun:

npm install nowaikit-sdk

bun add nowaikit-sdk

The package includes TypeScript declarations out of the box — no separate @types package needed.

{
  "dependencies": {
    "nowaikit-sdk": "^2.0.0"
  }
}

What's New in v2.0.0

SDK v2.0.0 is a major release that adds six new modules alongside the existing CRUD and fluent query capabilities:

A2A Client Quick Example

The A2A (Agent-to-Agent) client enables communication between AI agents using the A2A protocol. Discover agents, send tasks, and receive structured results:

import { A2AClient } from 'nowaikit-sdk/a2a';

const a2a = new A2AClient('http://localhost:3000');
const agent = await a2a.discoverAgent();

const result = await a2a.sendTask({
  message: {
    role: 'user',
    parts: [{ type: 'text', text: 'List active incidents' }]
  }
});

console.log(result);

Quick Example

Connect to your ServiceNow instance and start making API calls in seconds:

import { NowAIKit } from 'nowaikit-sdk';

const kit = new NowAIKit({
  instance: 'your-instance.service-now.com',
  auth: { type: 'basic', username: 'admin', password: 'password' }
});

// Query incidents
const incidents = await kit.incident.query({
  active: true,
  priority: 1,
  limit: 10
});

// Create a change request
const change = await kit.change.create({
  short_description: 'Deploy v2.1 to production',
  type: 'normal',
  risk: 'moderate'
});

console.log(`Found ${incidents.length} P1 incidents`);
console.log(`Created change: ${change.number}`);

Every method is fully typed. Your IDE will autocomplete field names, show parameter types, and flag errors at compile time.

Authentication Options

The SDK supports the same three authentication methods as the MCP integration. Choose the one that fits your environment:

Basic Auth

Simplest option for development and internal tools. Pass username and password directly.

const kit = new NowAIKit({
  instance: 'your-instance.service-now.com',
  auth: {
    type: 'basic',
    username: process.env.SN_USERNAME,
    password: process.env.SN_PASSWORD
  }
});

OAuth 2.0

Recommended for production. Uses client credentials flow with automatic token refresh.

const kit = new NowAIKit({
  instance: 'your-instance.service-now.com',
  auth: {
    type: 'oauth',
    clientId: process.env.SN_CLIENT_ID,
    clientSecret: process.env.SN_CLIENT_SECRET,
    username: process.env.SN_USERNAME,
    password: process.env.SN_PASSWORD
  }
});

SSO / OIDC (Enterprise)

For enterprise environments with SSO or OIDC identity providers. Pass an existing access token.

const kit = new NowAIKit({
  instance: 'your-instance.service-now.com',
  auth: {
    type: 'token',
    accessToken: process.env.SN_ACCESS_TOKEN
  }
});

See the OAuth Setup Guide for step-by-step instructions on configuring OAuth in ServiceNow.

Multi-Instance

Connect to multiple ServiceNow instances simultaneously. Each instance gets its own authenticated client:

import { NowAIKit } from 'nowaikit-sdk';

// Production instance
const prod = new NowAIKit({
  instance: 'prod.service-now.com',
  auth: { type: 'oauth', clientId: '...', clientSecret: '...', username: '...', password: '...' }
});

// Development instance
const dev = new NowAIKit({
  instance: 'dev.service-now.com',
  auth: { type: 'basic', username: 'admin', password: 'admin' }
});

// Compare incident counts across environments
const prodIncidents = await prod.incident.query({ active: true, limit: 0 });
const devIncidents = await dev.incident.query({ active: true, limit: 0 });

console.log(`Prod: ${prodIncidents.length} active incidents`);
console.log(`Dev: ${devIncidents.length} active incidents`);

For advanced multi-instance patterns (failover, load balancing, environment promotion), see the Full Multi-Instance Guide.

Available Modules

The SDK exposes the same 32 module categories as the MCP integration, covering the full breadth of the ServiceNow platform:

Next Steps

You are set up and ready to build. Here is where to go from here:

• SDK API Reference — Full documentation of every module, method, parameter, and return type.
• Fluent Query Guide — Advanced GlideQuery-style queries, batch operations, and server-side script execution.
• OAuth Setup Guide — Configure OAuth 2.0 in ServiceNow for production-ready authentication.
• Multi-Instance Guide — Advanced patterns for managing dev, test, and production environments.
• 450+ Tools Reference — Complete reference for every operation available across all 32 modules.
• Full Documentation — Everything else: MCP setup, client configuration, examples, and more.