mfa-servicenow-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| MCP_TOOL_PACKAGE | No | Tool package to load | standard |
| SERVICENOW_DEBUG | No | Enable debug logging | false |
| SERVICENOW_API_KEY | No | API key for API key auth | |
| SERVICENOW_TIMEOUT | No | HTTP request timeout in seconds | 30 |
| SERVICENOW_PASSWORD | No | Password for basic auth, OAuth, or browser prefill | |
| SERVICENOW_USERNAME | No | Username for basic auth, OAuth, or browser prefill | |
| SERVICENOW_AUTH_TYPE | No | Auth mode: basic, browser, oauth, api_key | basic |
| SERVICENOW_CLIENT_ID | No | OAuth client ID | |
| SERVICENOW_TOKEN_URL | No | OAuth token URL (defaults to instance/oauth_token.do) | |
| SERVICENOW_INSTANCE_URL | No | ServiceNow instance URL | |
| SERVICENOW_WRITE_GUARDS | No | Enable/disable all write guards | on |
| SERVICENOW_CLIENT_SECRET | No | OAuth client secret | |
| SERVICENOW_DEP_MAX_DEPTH | No | Maximum dependency depth for cross-scope resolution (1-6) | 2 |
| SERVICENOW_MCP_HTTP_HOST | No | Host for HTTP transport | 127.0.0.1 |
| SERVICENOW_MCP_HTTP_PATH | No | Streamable HTTP endpoint path | /mcp |
| SERVICENOW_MCP_HTTP_PORT | No | Port for HTTP transport | 8000 |
| SERVICENOW_MCP_TRANSPORT | No | MCP transport: stdio or http | stdio |
| SERVICENOW_API_KEY_HEADER | No | Header name for API key auth | X-ServiceNow-API-Key |
| SERVICENOW_ACTIVE_INSTANCE | No | Active instance alias for write operations | |
| SERVICENOW_BROWSER_TIMEOUT | No | Login timeout in seconds | 120 |
| SERVICENOW_INSTANCE_CONFIG | No | JSON string mapping alias to per-instance settings | |
| SERVICENOW_TLS_IMPERSONATE | No | Enable/disable browser-grade TLS impersonation | on |
| SERVICENOW_BROWSER_HEADLESS | No | Run browser without GUI | false |
| SERVICENOW_BROWSER_LOGIN_URL | No | Custom login page URL | |
| SERVICENOW_BROWSER_PROBE_PATH | No | Session validation endpoint | |
| SERVICENOW_BROWSER_SESSION_TTL | No | Session TTL in minutes | 30 |
| SERVICENOW_BROWSER_USER_DATA_DIR | No | Override Chromium profile path | |
| SERVICENOW_CONCURRENT_EDIT_GUARD | No | Enable/disable concurrent edit guard | on |
| SERVICENOW_MCP_HTTP_ALLOWED_HOSTS | No | Comma-separated Host allowlist for DNS rebinding protection | 127.0.0.1,::1,localhost |
| SERVICENOW_MCP_HTTP_JSON_RESPONSE | No | Return JSON responses instead of SSE streams | false |
| SCRIPT_EXECUTION_API_RESOURCE_PATH | No | Resource path for script execution API | |
| SERVICENOW_CONCURRENT_EDIT_WINDOW_MIN | No | Time window for concurrent edit detection in minutes | 10 |
| SERVICENOW_MCP_HTTP_DISABLE_DNS_REBINDING_PROTECTION | No | Disable DNS rebinding protection | false |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Live-first: answer questions with live queries (sn_query, sn_aggregate, sn_discover, targeted reads). Source downloads (download_app_sources / download_portal_sources) are optional for deep offline analysis — never a prerequisite for answering.
Flow/Action Designer versioning: the *_base and *_snapshot tables (e.g. sys_hub_action_type_base, sys_hub_flow_snapshot) hold published/draft version copies sharing the SAME name/internal_name as the live record — multiple same-named rows there are versions, NOT duplicates. Query the *_definition table (e.g. sys_hub_action_type_definition) for the one live record.
Playwright Chromium is missing; downloading the matching build automatically in the background. Retry your browser action in a moment. If it does not resolve, run: playwright install chromium
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| list_tool_packagesB | Lists available tool packages and the currently loaded one. |
| sn_healthB | Check ServiceNow API connectivity, auth status, Chromium install state (browser auth), and MCP server version. |
| sn_queryB | Query any table by encoded query. Pass fields. Use sn_aggregate to count, and domain tools for code search when enabled. |
| sn_aggregateA | Run COUNT/SUM/AVG/MIN/MAX on any table with optional group_by. Returns stats without fetching records. |
| sn_schemaB | Fetch field names, types, labels, and constraints from sys_dictionary for a given table. |
| sn_discoverA | Find tables by name or label keyword. Returns table name, label, scope, and parent class. |
| sn_resolve_urlA | Parse a ServiceNow URL → table, sys_id, scope, suggested next tool. Read-only. |
| get_widget_bundleC | Fetch full widget bundle (HTML, scripts, providers, CSS/JS dependencies) in one call. Analysis starting point. |
| get_portal_component_codeC | Fetch widget/provider/SI fields. Returns full body by default. Never chunk for analysis. |
| search_portal_regex_matchesA | True regex over portal code (widget/provider/SI), offsets+context. Server-table keyword search: search_server_code. |
| trace_portal_route_targetsA | Map widget→provider→route relationships. Metadata only, no script bodies. |
| download_portal_sourcesB | Targeted portal widgets/providers. Whole app: download_app_sources. widget_ids=one widget. |
| diff_local_componentB | Diff local edits vs remote (or compare_to root); verdict=True status-only, refresh=True fast-forwards. |
| download_attachmentC | Download attachments. Use saved_path locally; read the ResourceLink remotely when needed. |
| verify_deployment_xmlA | Compare a deploy XML to the live server. preflight=would it revert work, postflight=did it land. |
| manage_flow_designerA | Flow Designer read/analyse: structure, conditions, executions, cross-instance compare, action source. No write API: build/edit by driving Workflow Studio with act_in_debug_window yourself, then verify with get_detail. |
| query_local_graphB | Offline dependency/impact answers from audit graph files (0 API). uses|used_by|page|impact. |
| get_logsB | Query ServiceNow logs. log_type: system/journal/transaction/background. Max 20 rows. |
| search_server_codeB | Fast keyword search across 22 server-side code types (SI/BR/ACL). Portal regex+snippets: search_portal_regex_matches. |
| get_metadata_sourceB | Get one source record (SI/BR/widget) by name/sys_id. Returns body; 'complete' flags if truncated preview. |
| extract_table_dependenciesC | GlideRecord table dependency graph from server scripts (SI/BR/widgets). Pass widget_id for one widget. |
| download_app_sourcesA | FULL/all source of an app scope to disk (all groups+deps). scope REQUIRED — ask user. Step 1, not portal. |
| analyze_widget_performanceC | Analyze widget performance — code patterns, transaction logs, provider usage. Returns findings with severity. |
| get_developer_changesB | List developer's recent changes across portal tables. Metadata only, use count_only first. |
| get_pageB | Get or list portal pages by URL path, title, or sys_id. Returns layout tree with widget placements. |
| get_widget_instanceB | Get widget instance placement on a page. Returns column, order, and config. Filter by page or widget. |
| manage_script_includeC | List/get/create/update/delete/execute a script include (table: sys_script_include). |
| manage_scripted_restC | CRUD Scripted REST services + resources (sys_ws_definition/sys_ws_operation). Use list/get to find sys_ids. |
| audit_local_sourcesA | Analyze downloaded sources locally (no API). Generates cross-ref graph, dead code, HTML report. |
| manage_widget_dependencyB | CRUD + link/unlink for widget Angular providers & CSS/JS dependencies. Use action=list first for sys_ids. |
| manage_workflowC | LEGACY Workflow engine ONLY (wf_workflow/wf_activity); export writes a version's full graph to disk; verify checks edits applied in the editor. Flow Designer -> manage_flow_designer. |
| export_record_xmlB | Build deploy XML from the LIVE server — the only legal source. Issues an origin cert. Read saved_path. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
| analyze/condition-check | Settle how an encoded query or condition really behaves (empty values, !=, OR order, unknown fields) by counting on a live instance |
| analyze/data-question | Answer a question about instance data, or change data in bulk, with the right tool instead of a Background Script |
| analyze/local-source-audit | Analyze downloaded app sources locally — cross-references, dead code, execution order, HTML report |
| explore/asset-itom-map | Table map and first queries for HAM, materials management, CMDB and ITOM work |
| explore/flow-trigger-tracing | What runs when a table changes, and what sets one field — rules, flows, workflows, notifications — proven on live records |
| explore/record-forensics | Reconstruct what happened to one record — who changed which field when, what approvals, flows, emails and errors followed |
| manage/app-source-download | Download all server-side source code for a ServiceNow application scope |
| manage/flow-designer-build | Build or edit a Flow Designer flow yourself by driving Workflow Studio in the debug browser, verifying every save on the server |
| manage/local-sync | Scan, diff, and push local portal source changes to ServiceNow with conflict detection |
| manage/ui-test-evidence | Run UI test cases in the debug browser and put screenshots + results into a workbook — without ever loading an image into context |
TDQS
Scored across 32 tools
Most tools target a distinct resource+action, and the descriptions actively cross-reference siblings (search_portal_regex_matches vs search_server_code, manage_workflow vs manage_flow_designer, download_portal_sources vs download_app_sources). The one genuinely fuzzy cluster is get_widget_bundle / get_portal_component_code / get_metadata_source, which all return source bodies for widget/provider/SI records and require reading the fine print to choose correctly.
The surface mixes a compact 'sn_' namespace (sn_query, sn_aggregate, sn_schema, sn_health) with a verb_noun snake_case family (get_logs, search_server_code, verify_deployment_xml, manage_script_include). Both styles are readable and internally coherent, but the two conventions side by side plus a few noun-only names (sn_schema, sn_health) keep it from being a clean single pattern.
32 tools is well past the point where an agent can hold the surface in mind, and several read/analysis tools could be folded into parameterized variants (e.g. the four download_* tools, the three source-fetch tools). ServiceNow is a broad domain so the count is defensible, but the set is heavier than the stated developer/analysis purpose requires.
Coverage is strong across the developer lifecycle: discovery, schema, query/aggregate, code search, portal source retrieval, deploy XML build and verify, local graph auditing, plus CRUD for script includes, scripted REST, widget dependencies, and workflow. Gaps remain on the write side of the portal model (get_page and get_widget_instance are read-only, and there is no generic record create/update/delete for arbitrary tables), which will occasionally force workarounds.