ServiceNow - Prisme.ai

The ServiceNow app provides read/write access to the ServiceNow ITSM platform via its Table API. It can be used either as a Builder app (automations call ServiceNow instructions directly) or as a remote MCP server consumed by an Knowledges agent — covering incidents, change requests, problems, service catalog, requests, attachments, users and groups.

ITSM Tickets

Incidents, changes and problems with transitions and work notes

Service Catalog

List, inspect and order catalog items with variables

Generic Table Access

Query any ServiceNow table with encoded queries and aggregates

Prerequisites

A ServiceNow instance (URL format: https://<instance>.service-now.com)
Either Basic Auth credentials (user with itil / admin role) or an OAuth2 client (client_credentials flow)
Roles required for the intended tables: itil for incidents, change_manager for changes, problem_manager for problems, sn_request_write for catalog requests, etc.

Usage as App
Usage as MCP

Installation

Go to Apps in your workspace
Search for ServiceNow and install it
Open the app instance configuration and fill in the required fields

Configuration

Field	Description
Instance URL	`https://<instance>.service-now.com`
Authentication Type	`basic` or `oauth2`
Username / Password	Required when `authType = basic`
OAuth2 Client ID / Client Secret	Required when `authType = oauth2` (uses `client_credentials` grant)
MCP Endpoint	Auto-populated on install — URL of the MCP endpoint for this instance
MCP API Key	Auto-populated on install — signed key used in the `mcp-api-key` header. Do not modify

Credentials are stored as workspace secrets. MCP Endpoint and MCP API Key are generated automatically by the onInstall flow and are only needed to expose this instance as an MCP server (see the next tab).

Available Instructions

Every instruction resolves credentials via buildAppAuth (Basic or OAuth2 depending on authType). Most list operations accept limit, offset, fields (comma-separated) and displayValue (true/false/all) to control the response shape.

displayValue controls how reference/choice fields are rendered: true → labels, false → sys_ids, all → both (under value and display_value).

Generic Table Access

Instruction	Arguments
`queryRecords`	`tableName`*, `query` (encoded query), `fields`, `limit`, `offset`, `displayValue`
`getRecord`	`tableName`, `sysId`, `fields`, `displayValue`
`getStats`	`tableName`*, `query`, `count`, `sumFields`, `avgFields`, `groupBy`

Incidents

Instruction	Arguments
`listIncidents`	`query`, `state` (`1`=New, `2`=InProgress, `3`=OnHold, `6`=Resolved, `7`=Closed), `priority` (`1`=Critical → `4`=Low), `assignedTo`, `assignmentGroup`, `fields`, `limit`, `offset`, `displayValue`
`getIncident`	`sysId` or `number` (e.g. `INC0010001`), `fields`, `displayValue`
`createIncident`	`shortDescription`*, `description`, `callerId`, `category`, `subcategory`, `impact` (`1`/`2`/`3`), `urgency` (`1`/`2`/`3`), `priority`, `assignmentGroup`, `assignedTo`, `cmdbCi`, `contactType`
`updateIncident`	`sysId`*, `state`, `shortDescription`, `description`, `impact`, `urgency`, `priority`, `assignmentGroup`, `assignedTo`, `workNotes`, `comments`, `closeCode`, `closeNotes`

Change Requests

Instruction	Arguments
`listChanges`	`query`, `state`, `priority`, `type` (`normal`/`standard`/`emergency`), `assignedTo`, `assignmentGroup`, `fields`, `limit`, `offset`, `displayValue`
`getChange`	`sysId`*, `fields`, `displayValue`
`createChange`	`changeType`* (`normal`/`standard`/`emergency`), `shortDescription`*, `description`, `category`, `priority`, `risk`, `impact`, `assignmentGroup`, `assignedTo`, `startDate`, `endDate`, `implementationPlan`, `backoutPlan`, `testPlan`, `cmdbCi`
`updateChange`	`sysId`*, `shortDescription`, `description`, `priority`, `risk`, `impact`, `assignmentGroup`, `assignedTo`, `startDate`, `endDate`, `implementationPlan`, `backoutPlan`, `testPlan`, `workNotes`
`getChangeTransitions`	`sysId`*
`transitionChange`	`sysId`, `state` (target state value)

startDate / endDate use the ServiceNow format YYYY-MM-DD HH:mm:ss (UTC on the instance timezone).

Problems

Instruction	Arguments
`listProblems`	`query`, `state`, `priority`, `assignedTo`, `assignmentGroup`, `fields`, `limit`, `offset`, `displayValue`
`getProblem`	`sysId`*, `fields`, `displayValue`
`createProblem`	`shortDescription`*, `description`, `category`, `impact`, `urgency`, `priority`, `assignmentGroup`, `assignedTo`, `cmdbCi`
`updateProblem`	`sysId`*, `state`, `shortDescription`, `description`, `priority`, `assignmentGroup`, `assignedTo`, `workaround`, `causeNotes`, `fixNotes`, `workNotes`

Service Catalog

Instruction	Arguments
`listCatalogItems`	`catalog`, `category`, `query`, `limit`, `offset`
`getCatalogItem`	`sysId`* (returns the item with its variables / form fields)
`orderCatalogItem`	`sysId`*, `quantity`, `variables` (object: form field values)

Requests & Request Items

Instruction	Arguments
`listRequests`	`query`, `fields`, `limit`, `offset`, `displayValue`
`getRequest`	`sysId`*, `fields`, `displayValue`
`listRequestItems`	`query`, `requestId` (filter by parent request sys_id), `fields`, `limit`, `offset`, `displayValue`

Attachments

Instruction	Arguments
`listAttachments`	`tableName`, `tableSysId`
`uploadAttachment`	`tableName`, `tableSysId`, `fileName`, `contentBase64`, `contentType`

Users & Groups

Instruction	Arguments
`listUsers`	`query`, `active`, `fields`, `limit`, `offset`
`getUser`	`sysId` or `username`, `fields`
`listGroups`	`query`, `active`, `fields`, `limit`, `offset`

Arguments flagged with * are required.

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

Attach a File

- ServiceNow.uploadAttachment:
    tableName: incident
    tableSysId: '{{incident.sys_id}}'
    fileName: vpn-logs.txt
    contentBase64: '{{logs_base64}}'
    contentType: text/plain

The ServiceNow app ships with a built-in MCP server. Each app instance gets its own signed mcp-api-key that encodes the workspace ID and a credentials lookup URL — ServiceNow credentials (Basic or OAuth2) are never passed through headers and are resolved server-side from the app configuration.

Plug into an Agent Creator capability

Agents consume MCP servers directly through Agent Creator capabilities. This is the preferred way to expose ServiceNow to an agent.

Create or open a workspace

From the Prisme.ai console, create a new workspace (or open the one that will host the connector).

Install the ServiceNow app

Open the workspace Imports panel, search for ServiceNow and install it.

Configure the credentials

Open the freshly installed app instance settings and fill in the required fields (see the Usage as App tab for the field-by-field reference).

Copy the MCP endpoint and API key

Still on the app instance configuration page, copy the values of MCP Endpoint and MCP API Key — both are generated automatically on install.

Open Agent Creator

Switch to Agent Creator and open the agent you want to extend.

Add a capability

Add a new capability to the agent:

If a dedicated ServiceNow capability exists — select it and paste the MCP API Key into the mcp-api-key field. The server URL is already wired.
Otherwise — select the generic custom_mcp capability, paste the MCP Endpoint into the Server URL field, then open the Headers field and add an mcp-api-key entry whose value is the MCP API Key copied earlier:
```
{
  "mcp-api-key": "your-mcp-api-key"
}
```

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 MCP exists and when to reach for it. 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, tasks, requested items, knowledge articles or service catalog entries. Examples: "List my open incidents", "Create a change request for the database upgrade tonight", "What's the status of INC0012345?", "Find the knowledge article on VPN troubleshooting". Prefer calling MCP tools directly over guessing, and confirm with the user before any destructive action (resolve an incident, close a problem, approve a change).

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

Legacy MCP Install (Advanced > Tools)

Use this flow to plug the ServiceNow MCP into an Knowledges agent that does not yet support the native MCP picker.

Install the ServiceNow app

Install and configure the app in the same workspace as your agent (see the Usage as App tab). Once configured, mcpEndpoint and mcpApiKey are auto-populated.

Copy the MCP credentials

Open the app instance config and copy the values of MCP Endpoint and MCP API Key.

Open your Knowledges project

Navigate to Advanced > Tools.

Add an MCP tool

Click Add and select the MCP tab.

Fill in the endpoint

Paste the MCP Endpoint URL copied from the app instance.

Add the auth header

In the Headers field, add the signed API key:

{
  "mcp-api-key": "your-mcp-api-key"
}

Save

The agent can now list and call ServiceNow tools through the MCP endpoint.

The signed mcp-api-key encodes the workspace ID and the getConfig webhook URL. The MCP server validates the signature using the central app secret and transparently fetches the ServiceNow instance URL and credentials (Basic or OAuth2) from the installed app. Credentials are cached per tenant for 10 minutes.

Authentication Modes

The MCP server uses whatever mode is configured on the app instance:

Basic Auth — authType: basic, sends Authorization: Basic <base64(username:password)> on every call.
OAuth2 Client Credentials — authType: oauth2, the MCP server exchanges clientId / clientSecret for an access token against /oauth_token.do and caches it, then sends Authorization: Bearer <token>.

Switch modes by editing the app instance configuration; no MCP tool lets you change credentials at runtime.

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` / `getProblem` / `createProblem` / `updateProblem`	Full problem lifecycle (supports `workaround`, `causeNotes`, `fixNotes`)

Service Catalog

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

Requests & Request Items

Tool	Description
`listRequests` / `getRequest`	Browse service catalog requests
`listRequestItems`	List 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` / `getUser`	List users or fetch one by `sysId` / `username`
`listGroups`	List user groups

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"
  }
}

updateIncident

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

State codes for incidents: 1 New, 2 In Progress, 3 On Hold, 6 Resolved, 7 Closed, 8 Canceled.

transitionChange

Use getChangeTransitions first to discover which target states are legal for a given change, then call transitionChange:

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

Common change states (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"
    }
  }
}

variables keys must match the catalog item’s variable names. Use getCatalogItem first to discover the expected variable set.

getStats

{
  "name": "getStats",
  "arguments": {
    "tableName": "incident",
    "query": "active=true",
    "count": true,
    "groupBy": "priority,assignment_group"
  }
}

Combine sumFields / avgFields (comma-separated) with groupBy to produce aggregates for reporting.

uploadAttachment

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

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

Error Handling

HTTP Status	Error	Solution
401	Unauthorized	Verify credentials; for OAuth2, check the `client_credentials` grant is enabled on the app 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 `sys_id` / `number` and that the record is not in a restricted domain
409	Conflict	State transition is not allowed — call `getChangeTransitions` to get valid targets
429	Rate Limited	The instance returned a `X-RateLimit-*` error — back off; ServiceNow also enforces per-user transaction quotas

Common Issues

“Instance 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. “Invalid API key” (MCP) — The mcp-api-key header does not match the central app secret. Reinstall the app instance to regenerate a signed key. 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.

External Resources

ServiceNow Table API

Official Table API reference

Encoded Query Strings

Operators and syntax for query

OAuth Inbound Setup

Create an OAuth Application Registry

Tool Agents

Plug MCP servers into Knowledges agents

ITSM Tickets

Service Catalog

Generic Table Access

​Prerequisites

​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

​Attach a File

​Plug into an Agent Creator capability

​Legacy MCP Install (Advanced > Tools)

​Authentication Modes

​Available Tools

​Generic Table Access

​Incidents

​Change Requests

​Problems

​Service Catalog

​Requests & Request Items

​Attachments, Users & Groups

​Tool Details

​queryRecords

​createIncident

​updateIncident

​transitionChange

​orderCatalogItem

​getStats

​uploadAttachment

​Error Handling

​Common Issues

​External Resources

ServiceNow Table API

Encoded Query Strings

OAuth Inbound Setup

Tool Agents

Prerequisites

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

Attach a File

Plug into an Agent Creator capability

Legacy MCP Install (Advanced > Tools)

Authentication Modes

Available Tools

Generic Table Access

Incidents

Change Requests

Problems

Service Catalog

Requests & Request Items

Attachments, Users & Groups

Tool Details

queryRecords

createIncident

updateIncident

transitionChange

orderCatalogItem

getStats

uploadAttachment

Error Handling

Common Issues

External Resources