ServiceNow - Prisme.ai

The ServiceNow app exposes the ServiceNow ITSM platform through its Table API. It can be consumed two ways: as a remote MCP server that Agent Factory agents call as tools, or as a Builder app whose instructions you call directly from DSUL. It covers incidents, change requests, problems, the service catalog, requests, attachments, users and groups — plus a generic table accessor for any other ServiceNow table. Authentication is a per-workspace credential resolved server-side: either Basic Auth (a ServiceNow user with the right roles) or an OAuth2 client (client_credentials grant). Agents are identified by the capability Scope context_id,agent_id,user_id; the credential is never passed through the agent.

ITSM Tickets

Create, read, update and transition incidents, change requests and problems with work notes and close codes.

Service Catalog

List and inspect catalog items, then order them with their variables — creating a request and request item.

Generic Table Access

Query any ServiceNow table with encoded queries, fetch records by sys_id, and compute aggregate statistics.

Who is this for?

This connector is used by three different roles. Jump to the section that matches yours — each one is self-contained.

Agent builder

You build agents in Agent Factory and want them to manage ServiceNow tickets. → Agent builder tab.

Platform admin

You run the platform and want to publish ServiceNow as a reusable capability. → Platform admin setup accordion below.

Workspace builder

You write Builder automations (DSUL) that call ServiceNow operations directly. → Workspace builder tab.

Prerequisites (ServiceNow side)

A ServiceNow instance — its URL has the form https://<instance>.service-now.com.
A credential, one of:
- Basic Auth — a ServiceNow user (username + password) holding the roles needed for the tables you target.
- OAuth2 client (client_credentials grant) — create an Application Registry in ServiceNow under System OAuth > Application Registry and note its Client ID / Client Secret.
The roles for the tables you intend to use: itil for incidents, change_manager for change requests, problem_manager for problems, sn_request_write for catalog requests, and a table-specific role for anything else. The generic table tools are ACL-filtered by the account’s effective roles.

Platform admin (Governance) — one-time platform setup

Goal: ServiceNow is a per-workspace connector — each workspace pastes its own ServiceNow credential (see the Workspace builder tab), so there is no platform-wide credential to provision. The only optional platform task is to publish ServiceNow as a reusable capability in AI Governance so agent builders can enable it from the catalog instead of pasting a raw MCP endpoint.

There is no shared ServiceNow credential and no central OAuth client for this connector. The ServiceNow instance URL and credentials (Basic or OAuth2) always live in the consuming workspace. A Governance capability you publish here points at a specific workspace’s MCP endpoint; that workspace still owns the credential.

Declare the capability in AI Governance (optional)

Open AI Governance > Capabilities

Create (or edit) the ServiceNow capability.

Point it at the MCP endpoint

Set the capability’s MCP server URL to the connector’s MCP Endpoint (the workspace running the connector), and set its Scope to:

context_id,agent_id,user_id

The agent_id in the scope is what lets the connector identify the calling agent.

Make it available to agent builders

Once created, the capability appears in the capability picker for agent builders in your organization, who enable it on their agents. Access to the catalog follows your organization’s existing roles; there is no per-capability role grant.

Declaring the capability makes the connector available; it does not by itself authorize a specific agent against a ServiceNow instance. The ServiceNow credential is resolved server-side from the workspace running the connector, and ServiceNow ACLs (the account’s effective roles) are the final authorization boundary. There is no OAuth auth-config JSON to attach in Governance: authentication is a server-side Basic or client_credentials credential, not a per-user OAuth flow.

Agent builder (Agent Factory)
Workspace builder (DSUL)

Agent builder

Goal: let an agent you build in Agent Factory manage ServiceNow tickets through MCP tools.

Before an agent can call the connector, a Workspace builder must have installed and configured the ServiceNow app in a workspace (see the Workspace builder tab). Optionally, a Platform admin may have published a ServiceNow capability in AI Governance (see the Platform admin setup accordion above).

The ServiceNow credential (Basic or OAuth2) is resolved server-side from the workspace’s app configuration — it is never exposed to the agent. Your agent is identified by the agent_id that Agent Factory injects through the capability Scope.

Install and configure the connector in a workspace

Follow the Workspace builder tab: install ServiceNow in a workspace, then fill in the instance URL and credentials (Basic or OAuth2).

Add the MCP capability to your agent

In your agent, add a capability pointing at the workspace’s MCP Endpoint URL, and set its Scope to:

context_id,agent_id,user_id

The agent_id is what lets the connector identify your agent. The server URL is the connector’s MCP Endpoint, auto-populated when the app is installed.

Save

The agent now has access to every ServiceNow tool exposed by the MCP server.

Brief the agent in its system prompt

Wiring the capability is not enough — the agent also needs to know the tools exist and when to use them. Add a short paragraph to the agent’s system prompt. Copy-pasteable starter:

You have access to the ServiceNow MCP server. Use it whenever the user asks about ITSM data — incidents, change requests, problems, requested items, the service catalog, attachments, users or groups. Examples: "List my open incidents", "Create a change request for the database upgrade tonight", "What's the status of INC0012345?", "Order a new laptop from the catalog". Prefer calling MCP tools directly over guessing, and confirm with the user before any destructive action (resolve an incident, close a problem, transition a change).

Refine the trigger keywords (assignment groups, ticket prefixes, catalog item names) so the agent reliably picks up the right intent in your context.

Legacy AI Knowledge agents (no native MCP picker): add the connector under Advanced > Tools > MCP and paste the MCP Endpoint URL. The agent’s identity is still propagated so the connector can read its agent_id.

Available Tools

Generic Table Access

Tool	Description
`queryRecords`	Query any ServiceNow table using encoded query syntax
`getRecord`	Get a single record from any table by `sys_id`
`getStats`	Aggregate statistics for a table (count, sum, avg, min, max, group by)

Incidents

Tool	Description
`listIncidents`	List incidents (state / priority / assignedTo / assignmentGroup filters)
`getIncident`	Get an incident by `sysId` or `number`
`createIncident`	Create an incident
`updateIncident`	Update an incident (supports `workNotes`, `comments`, `closeCode`, `closeNotes`)

Change Requests

Tool	Description
`listChanges`	List change requests
`getChange`	Get a change request
`createChange`	Create a `normal` / `standard` / `emergency` change
`updateChange`	Update a change request
`getChangeTransitions`	Get available state transitions
`transitionChange`	Transition to a new state

Problems

Tool	Description
`listProblems`	List problems
`getProblem`	Get a problem
`createProblem`	Create a problem
`updateProblem`	Update a problem (supports `workaround`, `causeNotes`, `fixNotes`)

Service Catalog

Tool	Description
`listCatalogItems`	List available catalog items
`getCatalogItem`	Get a catalog item with its variables (form fields)
`orderCatalogItem`	Order a catalog item (creates a request + request item)

Requests & Request Items

Tool	Description
`listRequests`	List service catalog requests
`getRequest`	Get a service catalog request
`listRequestItems`	List request items (RITMs), optionally filtered by parent request

Attachments, Users & Groups

Tool	Description
`listAttachments`	List attachments on a record
`uploadAttachment`	Upload a file (base64) to a record
`listUsers`	List ServiceNow users
`getUser`	Get a user by `sysId` or `username`
`listGroups`	List ServiceNow user groups

Output Formats

Tools return the underlying ServiceNow Table API JSON. Most list and get operations accept a displayValue argument that controls how reference and choice fields are rendered:

false — raw sys_id values (the default for most fields).
true — human-readable labels.
all — both, under value and display_value.

List operations also accept limit, offset and fields (comma-separated) to control the response size and shape.

Tool Details

queryRecords

Query any ServiceNow table using the encoded query syntax.

{
  "name": "queryRecords",
  "arguments": {
    "tableName": "incident",
    "query": "active=true^priority=1^assignment_groupSTARTSWITHNetwork",
    "fields": "number,short_description,assigned_to,priority",
    "limit": 50,
    "displayValue": "all"
  }
}

Parameter	Required	Description
`tableName`	Yes	`incident`, `change_request`, `problem`, `sc_req_item`, `sys_user`, …
`query`	No	Encoded query (operators: `=`, `!=`, `STARTSWITH`, `CONTAINS`, `IN`, `^`, `^OR`, …)
`fields`	No	Comma-separated field names to return
`limit`	No	Max records (default 20)
`offset`	No	Pagination offset
`displayValue`	No	`true` / `false` / `all`

createIncident

{
  "name": "createIncident",
  "arguments": {
    "shortDescription": "VPN disconnects every 10 minutes",
    "callerId": "caller-sys-id",
    "category": "network",
    "impact": "2",
    "urgency": "2",
    "assignmentGroup": "Network Support",
    "contactType": "email"
  }
}

Parameter	Required	Description
`shortDescription`	Yes	Brief description of the incident
`callerId`	No	Caller `sys_id`
`category` / `subcategory`	No	Classification
`impact` / `urgency`	No	`1` / `2` / `3` — ServiceNow derives `priority` from these
`assignmentGroup` / `assignedTo`	No	Routing
`cmdbCi`	No	Affected configuration item `sys_id`
`contactType`	No	How reported: `email`, `phone`, `walk-in`, …

updateIncident

{
  "name": "updateIncident",
  "arguments": {
    "sysId": "incident-sys-id",
    "state": "6",
    "closeCode": "Solved (Permanently)",
    "closeNotes": "Rolled back the firmware to 7.2.1."
  }
}

Parameter	Required	Description
`sysId`	Yes	Incident `sys_id`
`state`	No	`1` New, `2` In Progress, `3` On Hold, `6` Resolved, `7` Closed, `8` Canceled
`workNotes`	No	Internal work notes (appended)
`comments`	No	Customer-visible comments (appended)
`closeCode` / `closeNotes`	No	Required by most workflows when resolving

transitionChange

Call getChangeTransitions first to discover which target states are legal for a given change, then transition:

{
  "name": "transitionChange",
  "arguments": {
    "sysId": "change-sys-id",
    "state": "-2"
  }
}

Parameter	Required	Description
`sysId`	Yes	Change request `sys_id`
`state`	Yes	Target state value. Common (model-dependent): `-5` New, `-4` Assess, `-3` Authorize, `-2` Scheduled, `-1` Implement, `0` Review, `3` Closed, `4` Canceled

orderCatalogItem

{
  "name": "orderCatalogItem",
  "arguments": {
    "sysId": "catalog-item-sys-id",
    "quantity": 1,
    "variables": {
      "laptop_model": "macbook_pro_16",
      "delivery_date": "2026-05-01"
    }
  }
}

Parameter	Required	Description
`sysId`	Yes	Catalog item `sys_id`
`quantity`	No	Quantity (default 1)
`variables`	No	Object of form field values. Keys must match the item’s variable names — call `getCatalogItem` first to discover them

uploadAttachment

{
  "name": "uploadAttachment",
  "arguments": {
    "tableName": "incident",
    "tableSysId": "incident-sys-id",
    "fileName": "vpn-logs.txt",
    "contentBase64": "VlBOIGxvZ3MgY29udGVudC4uLg==",
    "contentType": "text/plain"
  }
}

Parameter	Required	Description
`tableName`	Yes	Table the record belongs to
`tableSysId`	Yes	Record `sys_id`
`fileName`	Yes	Attachment file name
`contentBase64`	Yes	File content as a base64 string
`contentType`	No	MIME type (e.g. `text/plain`, `application/pdf`)

Max attachment size is set by the instance (default 1 GB via com.glide.attachment.max_size, but most instances restrict it further).

Workspace builder

Goal: install the connector in a workspace, configure the ServiceNow credential, and call its instructions from your automations.

Installation

Go to Apps in your workspace
Search for ServiceNow and install it
Open the app instance configuration and fill in the instance URL and credentials (Basic or OAuth2)

Configuration

Field	Description
Instance URL	`https://<instance>.service-now.com` — full URL with scheme
Authentication Type	`basic` or `oauth2`
Username / Password	Required when `authType = basic` (stored as workspace secrets)
OAuth2 Client ID / Client Secret	Required when `authType = oauth2` — uses the `client_credentials` grant (Client Secret stored as a workspace secret)
MCP Endpoint	Auto-populated on install — the URL of the MCP endpoint for this instance, used to wire the connector into an agent capability

The credential you provide selects the auth mode:

Auth mode	What you provide	Best for
Basic Auth (`authType: basic`)	A ServiceNow username + password	Quick setup; reuses an existing technical user and its roles
OAuth2 client credentials (`authType: oauth2`)	Client ID + Client Secret from an Application Registry	Token-based, server-to-server; the connector exchanges them at `/oauth_token.do` and caches the bearer

Credentials are stored as workspace secrets and resolved server-side on every call. Switch modes by editing the app instance configuration; no instruction lets you change credentials at runtime.

Available Instructions

Every instruction resolves the credential from the workspace configuration. Most list operations accept limit, offset, fields (comma-separated) and displayValue (true / false / all) to control the response shape.

Generic Table Access

Instruction	Description	Returns
`queryRecords`	Query any table by `tableName` (required) using an encoded `query`. `fields`, `limit`, `offset`, `displayValue` shape the response.	`{ result: [ { …record fields } ] }`
`getRecord`	Get one record by `tableName` (required) + `sysId` (required).	`{ result: { …record fields } }`
`getStats`	Aggregate statistics for `tableName` (required): `count`, `sumFields`, `avgFields`, grouped by `groupBy`, filtered by `query`.	`{ result: { stats: { count, … }, groupby_fields } }`

Incidents

Instruction	Description	Returns
`listIncidents`	List incidents filtered by `state`, `priority`, `assignedTo`, `assignmentGroup` and/or a raw `query`.	`{ result: [ { sys_id, number, short_description, … } ] }`
`getIncident`	Get one incident by `sysId` or `number` (e.g. `INC0010001`).	`{ result: { sys_id, number, state, … } }`
`createIncident`	Create an incident. `shortDescription` (required); plus `callerId`, `category`, `impact`, `urgency`, `assignmentGroup`, `contactType`, …	`{ result: { sys_id, number, … } }`
`updateIncident`	Update an incident by `sysId` (required). Supports `state`, `workNotes`, `comments`, `closeCode`, `closeNotes`, reassignment.	`{ result: { sys_id, number, state, … } }`

Change Requests

Instruction	Description	Returns
`listChanges`	List change requests filtered by `state`, `priority`, `type` (`normal`/`standard`/`emergency`), assignment and/or `query`.	`{ result: [ { sys_id, number, … } ] }`
`getChange`	Get one change request by `sysId` (required).	`{ result: { sys_id, number, state, … } }`
`createChange`	Create a change. `changeType` + `shortDescription` (required); plus `risk`, `impact`, `startDate`, `endDate`, `implementationPlan`, `backoutPlan`, `testPlan`, … Dates use `YYYY-MM-DD HH:mm:ss`.	`{ result: { sys_id, number, … } }`
`updateChange`	Update a change by `sysId` (required): schedule, plans, assignment, `workNotes`, …	`{ result: { sys_id, number, … } }`
`getChangeTransitions`	List the legal target states for a change by `sysId` (required).	`{ transitions: [ { state, label } ] }`
`transitionChange`	Move a change to a target `state` (required) by `sysId` (required).	`{ result: { sys_id, state, … } }`

Problems

Instruction	Description	Returns
`listProblems`	List problems filtered by `state`, `priority`, assignment and/or `query`.	`{ result: [ { sys_id, number, … } ] }`
`getProblem`	Get one problem by `sysId` (required).	`{ result: { sys_id, number, … } }`
`createProblem`	Create a problem. `shortDescription` (required); plus `category`, `impact`, `urgency`, assignment, `cmdbCi`.	`{ result: { sys_id, number, … } }`
`updateProblem`	Update a problem by `sysId` (required). Supports `state`, `workaround`, `causeNotes`, `fixNotes`, `workNotes`.	`{ result: { sys_id, number, … } }`

Service Catalog

Instruction	Description	Returns
`listCatalogItems`	List catalog items, optionally filtered by `catalog`, `category` or `query`.	`{ result: [ { sys_id, name, short_description } ] }`
`getCatalogItem`	Get one catalog item with its variables (form fields) by `sysId` (required).	`{ result: { sys_id, name, variables: [ … ] } }`
`orderCatalogItem`	Order an item by `sysId` (required), with `quantity` and a `variables` object of form values.	`{ result: { request_id, request_number, sys_id } }`

Requests & Request Items

Instruction	Description	Returns
`listRequests`	List service catalog requests, optionally filtered by `query`.	`{ result: [ { sys_id, number, … } ] }`
`getRequest`	Get one request by `sysId` (required).	`{ result: { sys_id, number, … } }`
`listRequestItems`	List request items (RITMs), optionally filtered by parent `requestId` or `query`.	`{ result: [ { sys_id, number, … } ] }`

Attachments, Users & Groups

Instruction	Description	Returns
`listAttachments`	List attachments on a record by `tableName` (required) + `tableSysId` (required).	`{ result: [ { sys_id, file_name, content_type, size_bytes } ] }`
`uploadAttachment`	Upload a base64 file to a record: `tableName`, `tableSysId`, `fileName`, `contentBase64` (all required) + `contentType`.	`{ result: { sys_id, file_name, download_link } }`
`listUsers`	List users, optionally filtered by `active` or `query`.	`{ result: [ { sys_id, user_name, name, email } ] }`
`getUser`	Get one user by `sysId` or `username`.	`{ result: { sys_id, user_name, name, email } }`
`listGroups`	List user groups, optionally filtered by `active` or `query`.	`{ result: [ { sys_id, name } ] }`

Returns shows the shape of the operation output. displayValue: all adds a display_value alongside each value for reference and choice fields.

DSUL Examples

Open an incident from a form

- ServiceNow.createIncident:
    shortDescription: VPN disconnects every 10 minutes
    description: '{{payload.message}}'
    callerId: '{{caller_sys_id}}'
    category: network
    impact: '2'
    urgency: '2'
    assignmentGroup: Network Support
    contactType: email
  output: incident

Assign and resolve

- ServiceNow.updateIncident:
    sysId: '{{incident.sys_id}}'
    assignedTo: '{{engineer_sys_id}}'
    state: '2'
    workNotes: Investigating the VPN concentrator logs.
- ServiceNow.updateIncident:
    sysId: '{{incident.sys_id}}'
    state: '6'
    closeCode: Solved (Permanently)
    closeNotes: Rolled back the firmware to 7.2.1.

Query with an encoded query

- ServiceNow.queryRecords:
    tableName: incident
    query: active=true^priority=1^assignment_groupSTARTSWITHNetwork
    fields: number,short_description,assigned_to,priority
    limit: 50
    displayValue: all
  output: critical

Order a catalog item

- ServiceNow.getCatalogItem:
    sysId: '{{laptop_item_id}}'
  output: item
- ServiceNow.orderCatalogItem:
    sysId: '{{laptop_item_id}}'
    quantity: 1
    variables:
      laptop_model: macbook_pro_16
      delivery_date: 2026-05-01
  output: request

Aggregate statistics

- ServiceNow.getStats:
    tableName: incident
    query: active=true
    count: true
    groupBy: priority,assignment_group
  output: stats

Error Handling

HTTP Status	Error	Solution
401	Unauthorized	Verify credentials; for OAuth2, check the `client_credentials` grant is enabled on the Application Registry
403	Forbidden	The user/client lacks an ACL on the target table — grant `itil`, `change_manager`, `problem_manager`, or a table-specific role
404	Not Found	Verify the `sys_id` / `number` and that the record is not in a restricted domain
409	Conflict	The state transition is not allowed — call `getChangeTransitions` to get the valid targets
429	Rate Limited	The instance returned a `X-RateLimit-*` error — back off; ServiceNow also enforces per-user transaction quotas
500	Server Error	A ServiceNow business rule or script failed — check the instance’s system logs

Common Issues

“ServiceNow not configured” — instanceUrl is missing from the app config. Paste the full URL with scheme (https://acme.service-now.com). “Basic Auth requires username and password” — authType is basic but one credential is empty. Either fill both or switch to oauth2. “OAuth2 requires clientId and clientSecret” — authType is oauth2 but the client credentials are missing. Create an Application Registry in ServiceNow (System OAuth > Application Registry) with the client_credentials grant and paste its Client ID / Client Secret. Empty results with a seemingly valid query — encoded queries are case-sensitive and ACL-filtered. Try displayValue: all and verify the effective roles of the account; a record outside the account’s domain is silently excluded.

External Resources

ServiceNow Table API

Official Table API reference

Encoded Query Strings

Operators and syntax for the query argument

OAuth Inbound Setup

Create an OAuth Application Registry

Tool Agents

Learn how Agent Factory agents consume MCP tools in Prisme.ai.

ITSM Tickets

Service Catalog

Generic Table Access

​Who is this for?

Agent builder

Platform admin

Workspace builder

​Prerequisites (ServiceNow side)

​Declare the capability in AI Governance (optional)

​Agent builder

​Brief the agent in its system prompt

​Available Tools

​Generic Table Access

​Incidents

​Change Requests

​Problems

​Service Catalog

​Requests & Request Items

​Attachments, Users & Groups

​Output Formats

​Tool Details

​queryRecords

​createIncident

​updateIncident

​transitionChange

​orderCatalogItem

​uploadAttachment

​Workspace builder

​Installation

​Configuration

​Available Instructions

​Generic Table Access

​Incidents

​Change Requests

​Problems

​Service Catalog

​Requests & Request Items

​Attachments, Users & Groups

​DSUL Examples

​Open an incident from a form

​Assign and resolve

​Query with an encoded query

​Order a catalog item

​Aggregate statistics

​Error Handling

​Common Issues

​External Resources

ServiceNow Table API

Encoded Query Strings

OAuth Inbound Setup

Tool Agents

Who is this for?

Prerequisites (ServiceNow side)

Declare the capability in AI Governance (optional)

Agent builder

Brief the agent in its system prompt

Available Tools

Generic Table Access

Incidents

Change Requests

Problems

Service Catalog

Requests & Request Items

Attachments, Users & Groups

Output Formats

Tool Details

queryRecords

createIncident

updateIncident

transitionChange

orderCatalogItem

uploadAttachment

Workspace builder

Installation

Configuration

Available Instructions

Generic Table Access

Incidents

Change Requests

Problems

Service Catalog

Requests & Request Items

Attachments, Users & Groups

DSUL Examples

Open an incident from a form

Assign and resolve

Query with an encoded query

Order a catalog item

Aggregate statistics

Error Handling

Common Issues

External Resources