ServiceNow Connector

The ServiceNow connector enables AxonFlow agents to interact with ServiceNow for IT service management, incident handling, change management, and CMDB operations with full policy enforcement and audit logging.

Overview

Property	Value
Type	servicenow
Edition	Enterprise
Auth Methods	OAuth 2.0, Basic Auth, API Key
Capabilities	query, execute, search, incidents, changes, cmdb

Use Cases

• Automate incident creation and triage for IT helpdesk bots
• Query CMDB for configuration item data in troubleshooting workflows
• Create and manage change requests programmatically
• Generate service desk reports and metrics summaries

Prerequisites

• AxonFlow Enterprise license (requires Enterprise Edition)
• ServiceNow instance (any supported version)
• One of the following authentication methods:
  • OAuth 2.0 (recommended for production)
  • Basic Auth with a service account
• Service account with appropriate ServiceNow roles: itil, cmdb_read (minimum)

ServiceNow OAuth Setup

1. In ServiceNow, navigate to System OAuth > Application Registry
2. Click New and select Create an OAuth API endpoint for external clients
3. Set the name (e.g., "AxonFlow Integration") and redirect URL
4. Copy the Client ID and Client Secret
5. Ensure the service account has the itil role assigned

Configuration

Environment Variables

# Required
MCP_servicenow_INSTANCE_URL="https://your-instance.service-now.com"

# Authentication - OAuth 2.0 (recommended)
MCP_servicenow_AUTH_TYPE="oauth2"
MCP_servicenow_CLIENT_ID="your-client-id"
MCP_servicenow_CLIENT_SECRET="your-client-secret"
MCP_servicenow_USERNAME="svc-axonflow"
MCP_servicenow_PASSWORD="secure_password"

# Authentication - Basic Auth (alternative)
# MCP_servicenow_AUTH_TYPE="basic"
# MCP_servicenow_USERNAME="svc-axonflow"
# MCP_servicenow_PASSWORD="secure_password"

# Optional
MCP_servicenow_TIMEOUT="30s"
MCP_servicenow_MAX_RETRIES="3"
MCP_servicenow_API_VERSION="v2"

Configuration Options

Option	Type	Required	Default	Description
instance_url	string	Yes	-	ServiceNow instance URL
auth_type	string	No	basic	Authentication type (oauth2, basic)
client_id	string	No*	-	OAuth 2.0 Client ID (required for OAuth)
client_secret	string	No*	-	OAuth 2.0 Client Secret (required for OAuth)
username	string	Yes	-	Service account username
password	string	Yes	-	Service account password
timeout	string	No	30s	Request timeout
max_retries	integer	No	3	Maximum retry attempts
api_version	string	No	v2	ServiceNow Table API version

Connector Config (Customer Portal)

{
  "name": "servicenow-itsm",
  "type": "servicenow",
  "options": {
    "instance_url": "https://your-instance.service-now.com",
    "auth_type": "oauth2",
    "timeout": 30,
    "max_retries": 3,
    "api_version": "v2"
  },
  "credentials": {
    "client_id": "your-client-id",
    "client_secret": "your-client-secret",
    "username": "svc-axonflow",
    "password": "secure_password"
  }
}

Installation

Install the ServiceNow connector via the connector marketplace API:

curl -X POST http://localhost:8081/api/v1/connectors/servicenow/install \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "name": "servicenow-itsm",
    "config": {
      "instance_url": "https://your-instance.service-now.com",
      "auth_type": "oauth2",
      "client_id": "your-client-id",
      "client_secret": "your-client-secret",
      "username": "svc-axonflow",
      "password": "secure_password"
    }
  }'

Operations

Search Incidents

curl -X POST https://your-axonflow.example.com/mcp/resources/query \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "connector": "servicenow-itsm",
    "statement": "incidents.search",
    "parameters": {
      "query": "priority=1^state=2^assignment_group=Network Support",
      "fields": ["number", "short_description", "priority", "state", "assigned_to", "opened_at"],
      "limit": 20,
      "order_by": "opened_at",
      "order_dir": "desc"
    }
  }'

Response:

{
  "success": true,
  "rows": [
    {
      "number": "INC0012345",
      "short_description": "Database connection errors in production",
      "priority": "1 - Critical",
      "state": "In Progress",
      "assigned_to": "Alice Johnson",
      "opened_at": "2025-12-07T10:30:00Z"
    }
  ],
  "row_count": 1,
  "duration_ms": 150,
  "connector": "servicenow-itsm"
}

Create an Incident

curl -X POST https://your-axonflow.example.com/mcp/tools/execute \
  -H "Content-Type: application/json" \
  -d '{
    "connector": "servicenow-itsm",
    "action": "incidents.create",
    "parameters": {
      "short_description": "API gateway returning 503 errors",
      "description": "Multiple users reporting 503 errors when accessing the API gateway. Began at approximately 14:00 UTC.",
      "category": "Network",
      "subcategory": "DNS",
      "impact": "2",
      "urgency": "1",
      "assignment_group": "API Platform Team",
      "caller_id": "monitoring-system"
    }
  }'

Response:

{
  "success": true,
  "rows_affected": 1,
  "message": "Incident created (number=INC0012346)",
  "duration_ms": 180,
  "connector": "servicenow-itsm"
}

Resolve an Incident

curl -X POST https://your-axonflow.example.com/mcp/tools/execute \
  -d '{
    "connector": "servicenow-itsm",
    "action": "incidents.resolve",
    "parameters": {
      "number": "INC0012345",
      "close_code": "Solved (Permanently)",
      "close_notes": "Root cause: connection pool exhaustion. Fix: increased max_connections from 50 to 200 and deployed hotfix v2.1.3."
    }
  }'

Query CMDB

curl -X POST https://your-axonflow.example.com/mcp/resources/query \
  -d '{
    "connector": "servicenow-itsm",
    "statement": "cmdb.query",
    "parameters": {
      "table": "cmdb_ci_server",
      "query": "operational_status=1^os_domain=production",
      "fields": ["name", "ip_address", "os", "ram", "cpu_count", "operational_status"],
      "limit": 50
    }
  }'

Create a Change Request

curl -X POST https://your-axonflow.example.com/mcp/tools/execute \
  -d '{
    "connector": "servicenow-itsm",
    "action": "changes.create",
    "parameters": {
      "short_description": "Upgrade PostgreSQL from 15 to 16",
      "description": "Scheduled upgrade of production PostgreSQL cluster from version 15.4 to 16.1.",
      "type": "Normal",
      "category": "Database",
      "risk": "Moderate",
      "impact": "2",
      "assignment_group": "Database Administration",
      "start_date": "2025-12-15T02:00:00Z",
      "end_date": "2025-12-15T06:00:00Z"
    }
  }'

Supported Operations

Operation	Description
incidents.search	Query incidents using encoded query strings
incidents.create	Create a new incident
incidents.update	Update incident fields
incidents.resolve	Resolve an incident with close code and notes
cmdb.query	Query CMDB configuration items
changes.create	Create a change request
changes.update	Update change request fields

Limitations

• Encoded query syntax: ServiceNow uses its own query language (encoded queries). Complex queries should be tested in ServiceNow's list view first.
• Rate limits: ServiceNow enforces rate limits based on instance type and plan. The connector handles 429 responses with automatic backoff.
• Record limits: Queries return a maximum of 10,000 records per request. Use limit and offset for pagination.
• ACL enforcement: ServiceNow Access Control Lists apply on top of AxonFlow policies. The service account must have visibility to the requested records.
• Attachment operations: Attachments are limited to the ServiceNow instance's max attachment size (default 24 MB).

Troubleshooting

Authentication Failed (401)

• Verify the service account credentials are correct
• For OAuth: check that the Client ID and Client Secret are valid and the application is active
• Ensure the service account is not locked or expired in ServiceNow
• Verify the instance URL includes the correct subdomain

Insufficient Rights (403)

• Check that the service account has the itil role for incident/change operations
• For CMDB queries: ensure the cmdb_read role is assigned
• Verify ACL rules allow the service account to access the requested table and fields

Record Not Found (404)

• Verify the record number or sys_id is correct
• Check that the service account has visibility to the record based on ACLs
• Ensure the table name is correct (e.g., incident, cmdb_ci_server, change_request)

Health Check

curl https://your-axonflow.example.com/mcp/connectors/servicenow-itsm/health

Response:

{
  "healthy": true,
  "latency_ms": 95,
  "details": {
    "instance_url": "https://your-instance.service-now.com",
    "instance_version": "Washington DC",
    "auth_type": "oauth2"
  }
}

Related

• Jira Connector
• Slack Connector
• MCP Overview
• Connector SDK