Connected Services Guide

The NowAIKit Main Panel shows two connected services: NowAIKit Builder (VS Code extension) and MCP Server. This guide explains what they are, how to connect them, and what you get when they're running.

What Are Connected Services?

How the Connection Works

NowAIKit Utils connects to Builder via a WebSocket bridge running on localhost:

Browser (NowAIKit Utils)
    |
    |  WebSocket (ws://localhost:8765)
    |
VS Code (NowAIKit Builder)
    |
    |  REST API / OAuth
    |
ServiceNow Instance
    |
    |  MCP Protocol
    |
AI Clients (Claude, Cursor, etc.)

• Utils auto-connects to Builder on every ServiceNow page load
• If Builder isn't running, Utils retries with exponential backoff (10s, 10s, 10s, then 30s)
• The connection is local only — no data leaves your machine
• Default port is 8765, configurable on both sides

Setting Up NowAIKit Builder

Follow these steps to connect NowAIKit Utils to NowAIKit Builder in VS Code.

Step 1: Install NowAIKit Builder in VS Code

Open VS Code and install the extension from the marketplace:

code --install-extension aartiq.nowaikit-builder

Or search for NowAIKit Builder in the VS Code Extensions view (Cmd+Shift+X / Ctrl+Shift+X).

Step 2: Connect to Your ServiceNow Instance

In VS Code, open the Command Palette (Cmd+Shift+P / Ctrl+Shift+P) and run:

NowAIKit: Connect to Instance

You'll be prompted for:

1. Instance URL — e.g. https://dev12345.service-now.com
2. Authentication method — Basic Auth (username + password) or OAuth 2.0 (browser-based, supports MFA/SSO)
3. Credentials — username/password for Basic Auth, or Client ID/Secret for OAuth

Once connected, you'll see the instance name in the VS Code status bar and the script/table explorers will populate.

Step 3: Start the Script Sync Bridge

The WebSocket bridge is what NowAIKit Utils connects to. Start it from the Command Palette:

NowAIKit: Start Script Sync

You'll see a sync icon in the VS Code status bar when the bridge is running.

Step 4: Verify in the Browser

Open (or reload) any ServiceNow page in Chrome/Firefox. Open the NowAIKit Main Panel (Ctrl+Shift+P / Cmd+Shift+P). Under Connected Services, you should see:

• NowAIKit Builder — Connected (or your instance name)
• MCP Server — Available

Script edits now sync bidirectionally between browser and VS Code.

Setting Up the MCP Server

The MCP Server provides enriched AI context to the Utils AI Assistant. It connects through NowAIKit Builder's WebSocket bridge — Builder must be running first.

Step 1: Install the MCP Server

npx nowaikit@latest

This starts the interactive setup wizard. Follow the prompts to configure your ServiceNow instance URL and credentials.

Step 2: Configure Your AI Client

Add NowAIKit as an MCP server in your AI client's configuration. See the Client Setup Guide for detailed instructions for each client (Claude Desktop, Claude Code, Cursor, VS Code, etc.).

Step 3: Ensure Builder Is Running

The MCP Server's data flows through Builder's WebSocket bridge to the browser extension. Make sure:

1. NowAIKit Builder is connected to your instance (Step 2 above)
2. The Script Sync bridge is started (Step 3 above)

When both are running, the Main Panel shows MCP Server: Available.

Configuration Options

WebSocket Port

Both sides must use the same port. Default is 8765.

To change the port in VS Code, open Settings (Cmd+,) and search for nowaikit syncPort.

Auto-Start Sync

Enable "nowaikit-builder.syncAutoStart": true in VS Code settings to start the WebSocket bridge automatically whenever you connect to an instance.

Auto-Connect (Utils)

By default, Utils auto-connects to Builder on every page load. This can be toggled via enableBridgeAutoConnect in the extension's sync storage. When disabled, the bridge only connects when manually triggered.

What You Get When Connected

With Builder Connected

• Two-way script sync — Edit a script field in ServiceNow and it appears in VS Code. Save in VS Code and it pushes to the browser. Real-time, via WebSocket.
• Script Explorer — Browse all Business Rules, Script Includes, Client Scripts, UI Actions, etc. from VS Code's sidebar.
• Table Explorer — Browse table schemas, fields, and relationships in VS Code.
• Update Set Manager — View and switch update sets from VS Code.
• Instance Dashboard — Node status, version, stats in VS Code.
• Connected status in Main Panel — Green dot and instance name shown in the browser.

With MCP Server Connected

• Enriched AI Assistant — The Utils AI sidebar gets live table schemas, record data, and instance configuration for better AI responses.
• AI context bridge — Your AI client (Claude, Cursor, etc.) can query your instance through the MCP protocol, and that context flows into the browser extension.
• "Available" status in Main Panel — Confirms the AI context pipeline is active.

Troubleshooting

Builder shows "Not running"

1. Open VS Code and check the status bar — is NowAIKit Builder connected to an instance?
2. Run NowAIKit: Start Script Sync from the Command Palette
3. Check the VS Code Output panel (select "NowAIKit" from the dropdown) for errors
4. Reload the ServiceNow page in the browser

MCP Server shows "Not available"

1. Builder must be running and connected first — fix the "Not running" issue above
2. Make sure the MCP server is installed (npx nowaikit@latest) and configured in your AI client
3. The MCP status updates automatically once Builder is connected

Connection drops / reconnects

• Utils auto-reconnects with exponential backoff (10s × 3, then 30s). No action needed.
• If VS Code restarts or the Builder extension reloads, Utils will reconnect on the next attempt.
• Check the browser DevTools console for [NowAIKit] messages if connection keeps failing.

Port conflict

If port 8765 is already in use by another application:

1. In VS Code Settings, change nowaikit-builder.syncPort to another port (e.g. 8766)
2. The browser extension will detect the new port from Builder's response
3. Restart the Script Sync bridge after changing the port

Firewall / Antivirus blocking

The WebSocket runs on localhost only — it never leaves your machine. If your firewall blocks local connections, add an exception for port 8765 (or your configured port) on 127.0.0.1.

Quick Reference