Serac Documentation

Installation

Requirements

• Node 20+ or Bun 1.2+ - Required runtime (ESM only; there is no CommonJS entrypoint)
• An MCP client - Claude Code, Claude Desktop, opencode, Cursor, Continue.dev, or any other
• ServiceNow instance - With OAuth configured
• LLM provider - Configured in your client, not here. The server never talks to a model.

Install via npm

# Global installation (recommended)
npm i -g @serac-labs/servicenow-mcp

# Verify installation
npm ls -g @serac-labs/servicenow-mcp

Quick Start

1. Register the server with your client

Write this into your MCP client's config file — Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json; Claude Code: .mcp.json in the project root; Cursor: .cursor/mcp.json. All three use the same mcpServers shape.

{
  "mcpServers": {
    "servicenow": {
      "command": "servicenow-mcp-stdio",
      "env": {
        "SNOW_INSTANCE": "https://acme.service-now.com",
        "SNOW_CLIENT_ID": "…",
        "SNOW_CLIENT_SECRET": "…",
        "SNOW_ENVIRONMENT_TYPE": "production"
      }
    }
  }
}

2. Check the connection

# Restart the client so it reads the new config, then ask for:
"Run snow_test_connection"

That tool authenticates and reads one row from sys_user. It reports back the instance URL it resolved, so you can see which instance you are actually pointed at before you write anything to it.

Do this deliberately, because the failure mode is quiet. A server that finds no usable credentials starts anyway, in unauthenticated mode, so the first symptom is an OAuth error surfacing inside some later tool call that had nothing to do with auth. Provoking it here tells you it is the credentials.

3. Start Building

# Just type your request in natural language:
"Create a widget showing high-priority incidents"

"Show me all incidents from last week"

"Create a business rule for auto-assignment"

The catalogue is large enough to blow a context window, so tools are deferred by default: tools/list returns two meta-tools, tool_search and tool_execute, and the model widens its own surface as it goes. Set SNOW_LAZY_TOOLS=false to register the whole catalogue up front instead.

Authentication Overview

Serac uses OAuth 2.0 for secure ServiceNow authentication. Credentials are stored securely and automatically refreshed.

Authentication Priority

Serac checks credentials in this order:

1. Environment variables - Highest priority
2. auth.json - Auto-loaded from the Serac TUI
3. .mcp.json credentials - Project-specific
4. Interactive login - Via /auth command in TUI

ServiceNow OAuth Setup

Create an OAuth application in your ServiceNow instance:

1. Navigate to System OAuth → Application Registry
2. Click New → Create an OAuth API endpoint for external clients
3. Configure:
   • Name: Serac
   • Redirect URL: http://localhost:3005/callback
   • Refresh Token Lifespan: 0 (unlimited)
4. Copy the Client ID and Client Secret

Credential Storage

Serac stores credentials securely at:

~/.local/share/serac/auth.json

This file is:

• Created automatically by /auth command in TUI
• Contains encrypted OAuth tokens
• Tokens are automatically refreshed
• Never synced to cloud or version control

Environment Variables (Alternative)

# ServiceNow credentials
SERVICENOW_INSTANCE_URL=https://your-instance.service-now.com
SERVICENOW_CLIENT_ID=your-client-id
SERVICENOW_CLIENT_SECRET=your-client-secret

# Optional: Pre-configured refresh token
SERVICENOW_REFRESH_TOKEN=your-refresh-token

LLM Providers

Serac supports 75+ AI providers via Models.dev. Configure via environment variables:

Using Ollama (Free, Local)

# Install Ollama
curl -fsSL https://ollama.com/install.sh | sh

# Pull a model
ollama pull llama3.3

# Configure Serac
DEFAULT_LLM_PROVIDER=ollama
OLLAMA_BASE_URL=http://localhost:11434
DEFAULT_OLLAMA_MODEL=llama3.3

Commands Reference

CLI Commands

The npm package puts these on your PATH. Neither one parses arguments — both are configured entirely through environment variables, so there is no --help to read and nothing useful happens if you pass a flag.

TUI Commands (inside Serac)

Type / followed by a command name. Most commands have keyboard shortcuts using ctrl+x as the leader key.

File References & Bash Commands

Use @ to reference files in your messages (fuzzy search). Use ! to run shell commands.

# Reference a file
How is auth handled in @src/auth/handler.ts?

# Run a shell command
!git status

# Both outputs are added to the conversation

Editor Setup

The /editor and /export commands use your EDITOR environment variable.

# Add to ~/.bashrc or ~/.zshrc
export EDITOR="code --wait"   # VS Code
export EDITOR="cursor --wait" # Cursor
export EDITOR="vim"           # Vim
export EDITOR="nano"          # Nano

Keyboard Shortcuts

Serac uses a leader key pattern (default: ctrl+x) to avoid conflicts with your terminal. Press the leader key first, then the shortcut.

Customize Keybinds

Override keybinds in your .mcp.json config. Use <leader> to reference the leader key, or "none" to disable.

{
  "$schema": "https://serac.build/config.json",
  "keybinds": {
    "leader": "ctrl+x",
    "app_help": "<leader>h",
    "session_compact": "none",
    "input_submit": "ctrl+enter"
  }
}

Configuration Reference

Configure Serac using .mcp.json (or .mcp.jsonc for comments). Supports JSON Schema for autocomplete.

Config Locations (by precedence)

Main Config Options

{
  "$schema": "https://serac.build/config.json",

  // Model configuration
  "model": "anthropic/claude-sonnet-4-20250514",
  "small_model": "anthropic/claude-3-5-haiku-20241022",

  // UI settings
  "theme": "serac",
  "autoupdate": true,

  // Tool restrictions
  "tools": {
    "write": false,    // Disable write tool
    "bash": false      // Disable bash tool
  },

  // Permission modes: "allow", "ask", "deny"
  "permission": {
    "edit": "ask",
    "bash": "ask"
  },

  // Sharing: "manual", "auto", "disabled"
  "share": "manual",

  // Instructions from files
  "instructions": ["CONTRIBUTING.md", "docs/*.md"],

  // Disable specific providers
  "disabled_providers": ["openai", "gemini"],

  // Provider configuration
  "provider": {},

  // Custom agents, commands, keybinds
  "agent": {},
  "command": {},
  "keybinds": {},

  // MCP servers
  "mcp": {}
}

Variable Substitution

Use {env:VAR_NAME} for environment variables, {file:path} for file contents.

{
  "model": "{env:SNOW_FLOW_MODEL}",
  "provider": {
    "openai": {
      "options": {
        "apiKey": "{file:~/.secrets/openai-key}"
      }
    }
  }
}

Agents

Serac uses specialized agents for different tasks. Switch agents with /agents or Tab.

Built-in Agents

Custom Agents

Define custom agents in .mcp.json or as markdown files in .serac/agent/.

{
  "agent": {
    "code-reviewer": {
      "description": "Reviews code for best practices",
      "model": "anthropic/claude-sonnet-4-20250514",
      "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
      "tools": {
        "write": false,  // Read-only agent
        "edit": false
      }
    }
  }
}

Or create .serac/agent/code-reviewer.md:

---
description: Reviews code for best practices
model: anthropic/claude-sonnet-4-20250514
tools:
  write: false
  edit: false
---

You are a code reviewer. Focus on security, performance, and maintainability.

Custom Commands

Create custom slash commands for repetitive tasks. Define in .mcp.json or as markdown files.

Quick Example

Create .serac/command/test.md:

---
description: Run tests with coverage
agent: build
---

Run the full test suite with coverage report.
Focus on failing tests and suggest fixes.

Now run /test in the TUI.

Command Features

Command Locations

• Global: ~/.config/serac/command/
• Per-project: .serac/command/

IDE Integration

Serac integrates with VS Code, Cursor, Windsurf, and any IDE with a terminal.

Keyboard Shortcuts

Installation

The extension installs automatically when you run serac in VS Code's integrated terminal.

Manual install: Search for Serac in the Extension Marketplace.

Tool Permissions

By default, Serac allows all operations. Configure granular controls in .mcp.json.

{
  "$schema": "https://serac.build/config.json",
  "permission": {
    "edit": "ask",       // Prompt before editing
    "bash": "ask",       // Prompt before bash commands
    "webfetch": "deny"   // Disable web fetching
  }
}

Permission Values

• "allow" — Allow without approval
• "ask" — Prompt for approval
• "deny" — Disable the tool

Granular Bash Permissions

{
  "permission": {
    "bash": {
      "git push": "ask",
      "git status": "allow",
      "terraform *": "deny",
      "*": "ask"
    }
  }
}

Project Rules (AGENTS.md)

Create an AGENTS.md file with custom instructions for Serac. Similar to Cursor rules.

Initialize

Run /init in the TUI to generate an AGENTS.md based on your project structure.

Example AGENTS.md

# My Project Rules

## Project Structure
- `packages/` - Workspace packages
- `infra/` - Infrastructure definitions

## Code Standards
- Use TypeScript with strict mode
- Shared code goes in `packages/core/`
- Follow ESLint and Prettier configs

Rule Locations

• Project: AGENTS.md in project root
• Global: ~/.config/serac/AGENTS.md

Custom Instruction Files

Include additional files via .mcp.json:

{
  "instructions": ["CONTRIBUTING.md", "docs/*.md", ".cursor/rules/*.md"]
}

Plugins

Extend Serac with JavaScript/TypeScript plugins. Place in .serac/plugin/ or ~/.config/serac/plugin/.

Basic Plugin Structure

// .serac/plugin/example.js
export const MyPlugin = async ({ project, client, $, directory }) => {
  console.log("Plugin initialized!")

  return {
    // Hook into events
    event: async ({ event }) => {
      if (event.type === "session.idle") {
        // Session completed
      }
    },

    // Intercept tool execution
    "tool.execute.before": async (input, output) => {
      if (input.tool === "read" && output.args.filePath.includes(".env")) {
        throw new Error("Do not read .env files")
      }
    }
  }
}

Themes

Select from built-in themes or create custom ones. Use /themes or set in config.

Built-in Themes

Custom Themes

Create JSON files in ~/.config/serac/themes/ or .serac/themes/.

Sharing Conversations

Create public links to share conversations. URL format: serac.build/s/<share-id>

Share Modes

Use /unshare to remove a shared conversation.

GitHub Integration

Use Serac in GitHub issues and PRs. Mention /serac or /oc in comments.

Features

• Triage issues and explain them
• Fix issues and implement features in a new branch
• Submit PRs with changes
• Runs securely in your GitHub Actions runner

Installation

serac github install

This sets up the GitHub App, workflow file, and secrets.

HTTP Server API

Run a headless HTTP server for programmatic access to Serac.

serac serve --port 4096 --hostname 127.0.0.1

API Endpoints

Troubleshooting

Log Files

• macOS/Linux: ~/.local/share/serac/log/
• Windows: %USERPROFILE%\.local\share\serac\log\

Run with --log-level DEBUG for detailed logs.

Common Issues

Getting Help

• GitHub Issues: github.com/serac-labs/serac/issues
• Discord: discord.gg/uGGrWj9KsT

TUI Workflow

The Serac TUI provides an interactive conversational interface for ServiceNow development:

# Create a widget
"Create a dashboard widget for incident metrics"

# Automate a process
"Create business rule to auto-assign incidents by category"

# Query and analyze
"Analyze incident trends from the past month"

# Complex task with multiple agents
"Build a complete workspace for IT support"

MCP Tools Overview

Serac provides 444 MCP tools across 135 functional domains, all accessible through natural language commands via the unified MCP architecture.

Complete Tool Reference

Loading the complete tool reference from the source of truth…

MCP Configuration

Every client passes the server its configuration as environment variables on the servicenow-mcp-stdio process. These are the names the server reads. Set both spellings of a field and the SERVICENOW_ one wins:

Use With Any AI IDE

Serac is a plain stdio MCP server, so any MCP-compatible client can run it. Point the client at the servicenow-mcp-stdio binary a global install puts on your PATH — there is no path to hunt for, and nothing generates a config file for you.

The mcpServers shape (Claude Code, Claude Desktop, Cursor)

{
  "mcpServers": {
    "servicenow": {
      "command": "servicenow-mcp-stdio",
      "env": {
        "SNOW_INSTANCE": "https://acme.service-now.com",
        "SNOW_CLIENT_ID": "…",
        "SNOW_CLIENT_SECRET": "…",
        "SNOW_ENVIRONMENT_TYPE": "production"
      }
    }
  }
}

The … placeholders are deliberate. Any value containing your- is discarded by the credential loader as a placeholder, so "your-client-id" left in a half-edited config starts the server unauthenticated rather than failing loudly. See MCP Configuration for what each variable does, and why SNOW_ENVIRONMENT_TYPE is the one that arms the production write guard.

Setup for Continue.dev

Continue.dev keeps its own schema; the command and the environment are the same.

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "servicenow-mcp-stdio",
          "args": [],
          "env": {
            "SNOW_INSTANCE": "https://acme.service-now.com",
            "SNOW_CLIENT_ID": "…",
            "SNOW_CLIENT_SECRET": "…",
            "SNOW_ENVIRONMENT_TYPE": "production"
          }
        }
      }
    ]
  }
}

Setup for opencode

opencode keys its servers under mcp and takes the command as an array, with the environment under environment rather than env.

{
  "mcp": {
    "servicenow": {
      "type": "local",
      "command": ["servicenow-mcp-stdio"],
      "environment": {
        "SNOW_INSTANCE": "https://acme.service-now.com",
        "SNOW_CLIENT_ID": "…",
        "SNOW_CLIENT_SECRET": "…",
        "SNOW_ENVIRONMENT_TYPE": "production"
      },
      "enabled": true
    }
  }
}

Streamable HTTP instead of stdio

The package also exports a Hono app on /http for clients that speak streamable HTTP. Read the tenancy note in the package README before deploying it: stdio is single-tenant by design, HTTP keys every cache by tenant and refuses a request it cannot place, and none of that state is shared between processes — so an HTTP deployment runs single-replica or brings its own shared store.

ES5 JavaScript Requirement

ES6+ Features That WILL CRASH

// ALL OF THESE BREAK SERVICENOW:
const x = 5;                    // SyntaxError
let items = [];                 // SyntaxError
const fn = () => {};            // SyntaxError
var msg = `Hello ${name}`;      // SyntaxError
for (let item of items) {}    // SyntaxError
var {name, id} = user;          // SyntaxError
array.map(x => x.id);           // SyntaxError
class MyClass {}                // SyntaxError

Correct ES5 Syntax

// THESE WORK IN SERVICENOW:
var x = 5;
var items = [];
function fn() { return 'result'; }
var msg = 'Hello ' + name;
for (var i = 0; i < items.length; i++) {
  var item = items[i];
}
var name = user.name;
var id = user.id;

Update Set Management

Update Sets track ALL changes for deployment between instances. Always create an Update Set before making changes.

Workflow

// 1. Create Update Set FIRST
snow_update_set_manage({
  action: 'create',
  name: "Feature: Incident Dashboard",
  description: "Widget showing incident metrics"
});

// 2. Develop (changes auto-tracked)
snow_create_artifact({...});
snow_create_business_rule({...});

// 3. Complete Update Set
snow_update_set_manage({
  action: 'complete',
  update_set_id: 'sys_id_here'
});

Widget Coherence

ServiceNow widgets require perfect synchronization between Server Script, Client Script, and HTML Template.

The Three-Way Contract

// SERVER SCRIPT - Initialize data
data.message = "Hello";
data.items = [];
if (input.action === 'loadItems') {
  data.items = getItems();
}

// CLIENT SCRIPT - Handle UI interactions
c.loadItems = function() {
  c.server.get({action: 'loadItems'}).then(function() {
    console.log(c.data.items);
  });
};

// HTML TEMPLATE - Display data
<button ng-click="loadItems()">Load</button>
<div ng-repeat="item in data.items">{{item}}</div>

Coherence Checklist

• Every data.property in server is used in HTML/client
• Every ng-click="method()" in HTML has matching c.method in client
• Every c.server.get({action}) in client has matching if(input.action) in server

ServiceNow Permissions

Serac follows the principle of least privilege. Permissions are organized into 5 tiers — grant only what your team needs. We strongly recommend using a development or sandbox instance and following the standard DTAP/OTAP workflow.

Stakeholder Access (Read-Only)

For stakeholders using the portal AI chat or Serac TUI in read-only mode. No data can be created, modified, or deleted.

Tables accessed: incident, change_request, problem, sc_request, task_sla, cmdb_ci_*, kb_knowledge, sys_dictionary, sp_widget, sn_customerservice_case, and more.

Developer Access (5-Tier Model)

For developers using Serac to build on ServiceNow. Create a custom ServiceNow role with only the tiers your team needs.

API Endpoints Used (Developer)

Enterprise Features Enterprise

Serac Enterprise adds powerful integrations for team workflows:

Integration Setup

# In the TUI, authenticate with enterprise features
/auth

# Connect Jira
# (Follow prompts to authorize)

# Then in the TUI, complete a Jira story:
"Complete JIRA-1234"