> For the complete documentation index, see [llms.txt](https://docs.ilert.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ilert.com/ai-and-agents/mcp/hosted/servicenow.md).

# ServiceNow

Give an agent access to ServiceNow with OAuth, and which of its tools write data as soon as they are called.

#### Required permissions

<table><thead><tr><th width="217.15625">Tool</th><th width="179.953125">Required Permission</th><th>Description</th></tr></thead><tbody><tr><td><code>search_records</code></td><td><code>read</code></td><td>Search for records in ServiceNow using a query.</td></tr><tr><td><code>get_record</code></td><td><code>read</code></td><td>Get a specific record by sys_id.</td></tr><tr><td><code>natural_language_search</code></td><td><code>read</code></td><td>Search for records using natural language.</td></tr><tr><td><code>create_incident</code></td><td><code>write</code></td><td>Create a new incident in ServiceNow.</td></tr><tr><td><code>update_incident</code></td><td><code>write</code></td><td>Update an existing incident in ServiceNow.</td></tr><tr><td><code>comment_incident</code></td><td><code>write</code></td><td>Add a comment to an incident (customer visible).</td></tr><tr><td><code>add_incident_notes</code></td><td><code>write</code></td><td>Add work notes to an incident (internal).</td></tr><tr><td><code>create_case</code></td><td><code>write</code></td><td>Create a new case in ServiceNow.</td></tr><tr><td><code>update_case</code></td><td><code>write</code></td><td>Update an existing case in ServiceNow.</td></tr><tr><td><code>comment_case</code></td><td><code>write</code></td><td>Add a comment to a case (customer visible).</td></tr><tr><td><code>add_case_notes</code></td><td><code>write</code></td><td>Add work notes to a case (internal).</td></tr></tbody></table>

{% hint style="warning" %}
The `create_*`, `comment_*` and `add_*_notes` tools change data in ServiceNow as soon as the agent calls them — they are not held back for approval. Only enable the tools you actually want the agent to use, and restrict the ServiceNow account's write access accordingly.
{% endhint %}

#### Create OAuth application and credentials

Using the ServiceNow MCP server requires OAuth 2.0 application credentials (Client ID and Client Secret).

**Option 1: Create OAuth Application via ServiceNow UI**

{% stepper %}
{% step %}
Log in to your ServiceNow instance as an administrator
{% endstep %}

{% step %}
Navigate to **System OAuth** → **Application Registry** (or search for "Application Registry" in the filter navigator)
{% endstep %}

{% step %}
Click **New** to create a new OAuth application
{% endstep %}

{% step %}
Fill in the application details:

* **Name**: Enter a name (e.g., "ilert-mcp-agent")
* **Client ID**: This will be auto-generated (or you can specify a custom one)
* **Client Secret**: Click **Generate** to create a client secret
* **Redirect URL**: Leave blank or enter a placeholder (not required for API access)
* **Active**: Check this box
  {% endstep %}

{% step %}
Configure **OAuth Configuration**:

* **Grant Types**: Select **Client Credentials** (for server-to-server authentication)
* **Access Token Lifespan**: Set appropriate value (e.g., 3600 seconds)
  {% endstep %}

{% step %}
Configure **Scopes** (API access):

* Click **Add** in the Scopes section
* Add the following scopes:
  * `user_impersonation` - Required for API access
  * Or create custom scopes with read permissions for specific tables:
    * `incident.read`
    * `change_request.read`
    * `problem.read`
      {% endstep %}

{% step %}
Click **Submit** to save the application
{% endstep %}

{% step %}
Copy the **Client ID** and **Client Secret** immediately
{% endstep %}

{% step %}
Store these credentials securely. You will need both when setting up the ServiceNow MCP server in ilert.
{% endstep %}
{% endstepper %}

**Option 2: Create OAuth Application via ServiceNow API**

Alternatively, you can create an OAuth application using the ServiceNow REST API:

```bash
curl -X POST "https://your-instance.service-now.com/api/now/table/oauth_entity" \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic YOUR_BASE64_CREDENTIALS" \
  -d '{
    "name": "ilert-mcp-agent",
    "grant_type": "client_credentials",
    "active": true,
    "access_token_lifespan": 3600
  }'
```

After creation, retrieve the Client ID and Client Secret from the response or via the UI.

#### Create user and assign role

The OAuth application needs to be associated with a user that has appropriate permissions:

{% stepper %}
{% step %}
Navigate to **User Administration** → **Users** (or search for "Users" in the filter navigator)
{% endstep %}

{% step %}
Create a new user or select an existing user:

* **User ID**: Enter a unique user ID (e.g., "ilert.agent")
* **First Name**: Enter first name
* **Last Name**: Enter last name
* **Email**: Enter email address
* **Password**: Set a secure password
  {% endstep %}

{% step %}
Assign appropriate roles to the user:

* **itil** - ITIL role for incident and change management access
* **sn\_incident.read** - Read access to incidents
* **sn\_change\_request.read** - Read access to change requests
* **sn\_problem.read** - Read access to problems
* Or create a custom role with specific table read permissions
  {% endstep %}

{% step %}
Link the OAuth application to the user:

* Go back to **System OAuth** → **Application Registry**
* Open your OAuth application
* In the **User** field, select the user you created/selected
* Click **Update**
  {% endstep %}
  {% endstepper %}

#### Alternative: Use Basic Authentication (Not Recommended)

If OAuth is not available, you can use basic authentication:

1. Create a user in ServiceNow with appropriate roles (as described above)
2. Use the username and password when configuring the ServiceNow MCP server
3. Note: Basic authentication is less secure and not recommended for production use

#### Verify OAuth credentials

Before configuring the MCP server, verify that your OAuth credentials work:

```bash

# Test OAuth token generation
curl -X POST "https://your-instance.service-now.com/oauth_token.do" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"

# Test API access with the access token
curl -X GET "https://your-instance.service-now.com/api/now/table/incident?sysparm_limit=1" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"
```

Replace:

* `YOUR_CLIENT_ID` with your OAuth Client ID
* `YOUR_CLIENT_SECRET` with your OAuth Client Secret
* `YOUR_ACCESS_TOKEN` with the access token from the first request
* `your-instance` with your ServiceNow instance name

{% hint style="warning" %}
**Security Recommendations:**

* Use OAuth 2.0 Client Credentials flow for server-to-server authentication
* Regularly rotate Client Secrets
* Use the principle of least privilege - only grant access to tables and fields that are necessary
* Monitor OAuth application usage in ServiceNow audit logs
* Consider using IP restrictions if your ServiceNow instance supports it
  {% endhint %}

{% hint style="info" %}
**Note:**

* You'll need your ServiceNow instance URL (e.g., `https://your-instance.service-now.com`) when configuring the MCP server
* The instance URL format may vary for different ServiceNow deployments (e.g., custom domains)
* Ensure the user associated with the OAuth application has the necessary roles and permissions
  {% endhint %}

#### Connect ServiceNow with agent

To connect ServiceNow with your AI SRE agent:

{% stepper %}
{% step %}
Navigate to **Agents** in the ilert navigation menu
{% endstep %}

{% step %}
Open the agent detail view for the agent you want to configure
{% endstep %}

{% step %}
Go to the **Tools** tab
{% endstep %}

{% step %}
Under the **ilert hosted MCP servers** section, locate the **ServiceNow** card
{% endstep %}

{% step %}
Click **Connect** on the ServiceNow card
{% endstep %}

{% step %}
In the connection dialog that appears:

* **Select connector:** Choose "Create new connector" (or select an existing connector if you have one)
* **Type:** Select **OAuth 2.0** or **Basic Auth** from the dropdown (depending on your ServiceNow authentication method)
* **Secret name:** Enter a name for your connector (e.g., "ServiceNow Production" or "ServiceNow Main")
* **Secret value:** For OAuth 2.0, enter your Client ID and Client Secret (format: `client_id:client_secret`). For Basic Auth, enter username:password
* **Host URL:** Enter your ServiceNow instance URL (e.g., `https://your-instance.service-now.com`)
  {% endstep %}

{% step %}
Click **Connect** to complete the connection
{% endstep %}

{% step %}
After connecting, you can enable or disable specific tools needed for alert investigation, such as:

* `search_records` - Search for records in ServiceNow using a query
* `get_record` - Get a specific record by sys\_id
* `natural_language_search` - Search for records using natural language
* `create_incident` - Create a new incident in ServiceNow
* `update_incident` - Update an existing incident in ServiceNow
* `comment_incident` - Add a comment to an incident (customer visible)
* `add_incident_notes` - Add work notes to an incident (internal)
* `create_case` - Create a new case in ServiceNow
* `update_case` - Update an existing case in ServiceNow
* `comment_case` - Add a comment to a case (customer visible)
* `add_case_notes` - Add work notes to a case (internal)
  {% endstep %}
  {% endstepper %}

The ServiceNow integration is now connected and ready to use for root cause analysis.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.ilert.com/ai-and-agents/mcp/hosted/servicenow.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.