Agentic Data Plane

beta

ServiceNow Managed MCP Server

The ServiceNow managed MCP server lets agents work with a ServiceNow instance through the REST Table API: search, create, and update incidents, append work notes, search the knowledge base, look up users and assignment groups, discover table schema and field choices, and read allow-listed tables.

After reading this page, you will be able to:

Configure the ServiceNow managed MCP server with Basic authentication, OAuth client credentials, or User OAuth
Use projections and hierarchies to shape responses and gate table reads
Search, create, and update incidents and read allow-listed records from the Inspector or an agent

What this MCP server does

Wraps the ServiceNow REST Table API. The MCP is vendor-generic: ServiceNow records are returned as opaque JSON objects (their field set varies by instance), and the agent learns each table’s shape and valid field values at runtime through the discovery tools (get_table_schema, get_field_choices).

Customer-specific structure is supplied as configuration, not code:

Projections set the default field list returned per table (a ServiceNow incident carries about 100 fields, so projections keep responses small) and gate which tables the generic query_records tool may read.
Hierarchies declare dependent-field chains (for example, service area, then category, then subcategory). The agent reads the chain order with describe_field_hierarchies and resolves each field’s valid values at runtime with get_field_choices. No field values are stored in the configuration.

It is not a general SQL interface, and it does not delete records: writes are limited to the typed incident tools plus generic record reads.

Prerequisites

Before you create the server, make sure you have:

A ServiceNow instance and its URL (for example, https://acme.service-now.com).
A ServiceNow service account, or an OAuth client, with the roles your workflows need (typically itil for incidents, knowledge for the knowledge base, and read access to sys_dictionary and sys_choice for schema discovery).
For User-OAuth mode: an OAuth Provider configured in Redpanda ADP. See Configure an OAuth Provider.

Choose an authentication method

The MCP authenticates to ServiceNow as a single principal; it does not impersonate end-users. When creating an incident, the agent passes the requesting user’s sys_id in caller_id. Pick one of three methods:

Basic authentication (simplest): A dedicated ServiceNow user (for example, svc_redpanda) and its password. The username is plaintext; the password lives in the ADP secret store.
OAuth client credentials (service account): An OAuth API client registered under System OAuth > Application Registry. ServiceNow’s token endpoint is https://<instance>.service-now.com/oauth_token.do.
User OAuth: Per-user delegation through an OAuth Provider. ServiceNow’s recommended integration model is the service account, so prefer Basic authentication or OAuth client credentials unless you specifically need per-user attribution.

Configure

Create a new ServiceNow MCP server in ADP:

Open MCP Servers > Create Server.
Pick ServiceNow from the marketplace picker.
Fill in identity fields (name, description).

In the ServiceNow configuration form:

Field Notes

Field	Notes
`instance_url`	Base URL of your ServiceNow instance (for example, `https://acme.service-now.com`). Must be an `https://` URL.
`auth`	`basic_auth`, `oauth`, or `user_oauth`.
`basic_auth` (Basic-auth mode)	`username` (ServiceNow service-account username, for example `svc_redpanda`) and `password_secret_ref` (secret-store reference, `UPPER_SNAKE_CASE`).
`oauth` (OAuth mode)	`client_id`, `client_secret_ref` (secret-store reference), and `token_url` (`https://<instance>.service-now.com/oauth_token.do`).
`user_oauth` (User-OAuth mode)	`provider_name` (the OAuth Provider you configured) and the minimum required scopes.
`projections`	Per-table default field lists and the read allow-list for `query_records`.
`hierarchies`	Dependent-field chains the agent resolves at runtime.

instance_url

Base URL of your ServiceNow instance (for example, https://acme.service-now.com). Must be an https:// URL.

auth

basic_auth, oauth, or user_oauth.

basic_auth (Basic-auth mode)

username (ServiceNow service-account username, for example svc_redpanda) and password_secret_ref (secret-store reference, UPPER_SNAKE_CASE).

oauth (OAuth mode)

client_id, client_secret_ref (secret-store reference), and token_url (https://<instance>.service-now.com/oauth_token.do).

user_oauth (User-OAuth mode)

provider_name (the OAuth Provider you configured) and the minimum required scopes.

projections

Per-table default field lists and the read allow-list for query_records.

hierarchies

Dependent-field chains the agent resolves at runtime.

Click Create.

Configure from the CLI

For a managed server, set the auth method inside the --managed-config JSON. The auth field is required.

Basic authentication
OAuth client credentials
User OAuth

rpk ai mcp create --name acme-servicenow --managed-config '{
  "@type": "type.googleapis.com/redpanda.mcps.servicenow.v1.ServiceNowMCPConfig",
  "instance_url": "https://acme.service-now.com",
  "basic_auth": {
    "username": "svc_redpanda",
    "password_secret_ref": "SERVICENOW_PASSWORD"
  },
  "projections": [
    {
      "table": "incident",
      "default_fields": ["number", "short_description", "state", "priority", "assignment_group", "caller_id"],
      "queryable": true
    },
    { "table": "change_request", "queryable": true }
  ],
  "hierarchies": [
    {
      "table": "incident",
      "name": "service",
      "fields": ["u_service_area", "u_service_category", "u_service_subcategory"]
    }
  ]
}'

rpk ai mcp create --name acme-servicenow-oauth --managed-config '{
  "@type": "type.googleapis.com/redpanda.mcps.servicenow.v1.ServiceNowMCPConfig",
  "instance_url": "https://acme.service-now.com",
  "oauth": {
    "client_id": "<oauth-client-id>",
    "client_secret_ref": "SERVICENOW_CLIENT_SECRET",
    "token_url": "https://acme.service-now.com/oauth_token.do"
  }
}'

rpk ai mcp create --name acme-servicenow-user --managed-config '{
  "@type": "type.googleapis.com/redpanda.mcps.servicenow.v1.ServiceNowMCPConfig",
  "instance_url": "https://acme.service-now.com",
  "user_oauth": {
    "provider_name": "servicenow-prod"
  }
}'

Replace <oauth-client-id> with the client ID from your ServiceNow OAuth application registry, and servicenow-prod with the name of the OAuth Provider you configured.

Tools

The ServiceNow MCP exposes tools across incidents, knowledge, schema discovery, lookups, and generic reads:

Tool Description

Tool	Description
`search_incidents`	Search incidents with a ServiceNow encoded query.
`get_incident`	Fetch one incident by `sys_id`.
`create_incident`	Create an incident (typed fields plus an `additional_fields` map for custom fields).
`update_incident`	Update state, assignment, notes, urgency, or impact, or resolve or close an incident.
`add_work_note`	Append a work note (internal) or comment (customer-visible) to an incident.
`search_knowledge`	Full-text search over published knowledge articles.
`get_article`	Fetch one knowledge article by `sys_id` or `number`.
`get_table_schema`	Field metadata (name, type, mandatory, reference) for a table, from `sys_dictionary`.
`get_field_choices`	Valid choice values for a field from `sys_choice`, optionally scoped to a parent value.
`describe_field_hierarchies`	Declared dependent-field chains for a table, from the server configuration.
`lookup_user`	Find users by name, email, or username; returns their `sys_id`.
`lookup_group`	Find assignment groups by name; returns their `sys_id`.
`query_records`	Read any allow-listed table with an encoded query.

search_incidents

Search incidents with a ServiceNow encoded query.

get_incident

Fetch one incident by sys_id.

create_incident

Create an incident (typed fields plus an additional_fields map for custom fields).

update_incident

Update state, assignment, notes, urgency, or impact, or resolve or close an incident.

add_work_note

Append a work note (internal) or comment (customer-visible) to an incident.

search_knowledge

Full-text search over published knowledge articles.

get_article

Fetch one knowledge article by sys_id or number.

get_table_schema

Field metadata (name, type, mandatory, reference) for a table, from sys_dictionary.

get_field_choices

Valid choice values for a field from sys_choice, optionally scoped to a parent value.

describe_field_hierarchies

Declared dependent-field chains for a table, from the server configuration.

lookup_user

Find users by name, email, or username; returns their sys_id.

lookup_group

Find assignment groups by name; returns their sys_id.

query_records

Read any allow-listed table with an encoded query.

Example: Search open incidents

curl -s https://aigw.<cluster-id>.clusters.rdpa.co/mcp/v1/acme-servicenow \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "search_incidents",
      "arguments": {
        "query": "active=true^priority=1"
      }
    }
  }'

Replace <cluster-id> with your cluster ID and $TOKEN with a gateway access token.

Example: Create an incident

The agent typically calls lookup_user and get_field_choices first to resolve caller_id and a valid category value.

curl -s https://aigw.<cluster-id>.clusters.rdpa.co/mcp/v1/acme-servicenow \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "create_incident",
      "arguments": {
        "short_description": "VPN drops every few minutes in Dresden",
        "caller_id": "a1b2c3d4e5f6...",
        "urgency": 2,
        "impact": 2,
        "category": "network"
      }
    }
  }'

Troubleshooting

Common symptoms and fixes:

Symptom What to check

Symptom	What to check
`401 Unauthorized`	Confirm the service-account credentials. For Basic authentication, check the username and `SERVICENOW_PASSWORD`; for OAuth, check the client ID, `SERVICENOW_CLIENT_SECRET`, and token URL.
`403 Forbidden`	The service account lacks the role for the operation (for example, `itil` for incidents or read access to `sys_dictionary` for `get_table_schema`). Grant the role in ServiceNow.
`query_records` rejects a table	The table is not listed in `projections` with `queryable` set to `true`. Add a projection entry for it.
`OAuthConnectionRequired` (User-OAuth mode)	First call from a user with no stored token. The user completes the ServiceNow OAuth consent flow, the token lands in the vault, and later calls reuse it. See User-delegated OAuth.

401 Unauthorized

Confirm the service-account credentials. For Basic authentication, check the username and SERVICENOW_PASSWORD; for OAuth, check the client ID, SERVICENOW_CLIENT_SECRET, and token URL.

403 Forbidden

The service account lacks the role for the operation (for example, itil for incidents or read access to sys_dictionary for get_table_schema). Grant the role in ServiceNow.

query_records rejects a table

The table is not listed in projections with queryable set to true. Add a projection entry for it.

OAuthConnectionRequired (User-OAuth mode)

First call from a user with no stored token. The user completes the ServiceNow OAuth consent flow, the token lands in the vault, and later calls reuse it. See User-delegated OAuth.

Limitations

This MCP server does not cover:

Record deletion: Writes are limited to the typed incident tools; the MCP never deletes records.
Arbitrary SQL: Reads go through the REST Table API and encoded queries, not a SQL interface. Use query_records against allow-listed tables instead.

Next steps

Was this helpful?

group Ask in the community

mail Share your feedback

group_add Make a contribution