servicenow-mcp-agent
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@servicenow-mcp-agent Investigate the payment service outage and suggest a resolution"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
servicenow-mcp-agent
An MCP server that exposes ServiceNow-style ITSM tools to a Claude agent, plus an eval harness that measures whether the agent actually uses them correctly.
The interesting part is not that the agent works. It is that the repo tells you how well it works, on 24 graded tasks, with three metrics: tool-selection accuracy, task-completion rate, and latency per call.
┌──────────────┐ Messages API ┌───────────────┐ MCP (stdio/HTTP) ┌──────────────────┐
│ Claude │◄─────tools────────│ ITSM agent │◄────tools/call───────│ MCP server │
│ (Sonnet 5) │─────tool_use─────►│ + tracing │─────tools/list──────►│ 14 ITSM tools │
└──────────────┘ └───────┬───────┘ └────────┬─────────┘
│ │
┌───────▼────────┐ ┌─────────▼──────────┐
│ eval harness │ │ backend interface │
│ 24 graded tasks│ ├────────────────────┤
│ metrics/report │ │ mock │ ServiceNow │
└────────────────┘ │ store │ Table API │
└────────────────────┘Quick start
git clone https://github.com/your-username/servicenow-mcp-agent
cd servicenow-mcp-agent
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest # 105 tests, no API key needed
export ANTHROPIC_API_KEY=sk-ant-...
snow-agent --list-tools
snow-agent -v "The payment service is down. What's the likely root cause?"
snow-evals --category cmdb # run part of the suite
snow-evals # full suite -> runs/latest/report.{md,html,json}No ServiceNow instance is required. The default backend is a deterministic in-memory fixture (16 incidents, 8 KB articles, 13 CIs with a real dependency graph, 10 users). To point at a free ServiceNow Personal Developer Instance instead, see docs/SERVICENOW_SETUP.md.
Related MCP server: snow-mcp
The 14 tools
Tool | Purpose |
| Primary discovery; named filters or a raw encoded query |
| One full record including work notes and comments |
| Log a new incident (validated references, derived priority) |
| Field changes and internal work notes |
| Customer-visible comment |
| The only path to Resolved; requires close code + notes |
| Fuzzy history search — "has this happened before?" |
| Grouped counts without pulling every record |
| KB search, then full text |
| Find configuration items; one CI plus its open incidents |
| Dependency graph: upstream causes, downstream blast radius |
| Resolve informal names, check VIP status |
Several pairs are deliberate near-neighbours (update_incident vs add_incident_comment,
search_incidents vs find_similar_incidents, get_ci vs get_ci_relationships). Distinguishing
them is exactly what tool-selection accuracy measures, and it is where a naive tool surface fails.
Evals
snow-evals # full suite
snow-evals --tasks resolve-vpn-with-kb # one task
snow-evals --category cmdb safety --concurrency 4
snow-evals --prompt minimal --out runs/minimal # prompt ablation
snow-evals --fail-under 0.8 # CI gateOutputs report.md, report.html, report.json and a traces.jsonl containing every tool call,
argument, latency and result preview.
What is measured
Tool-selection accuracy — per task, the set of distinct tools called versus the expected set,
macro-averaged so every task weighs the same. Tasks also declare optional_tools (a defensible
alternative route, excluded from the precision denominator) and forbidden_tools (a real mistake,
e.g. calling create_incident when the incident already exists). Reported as precision / recall /
F1, exact-set match, first-tool accuracy, and forbidden-tool rate.
Task-completion rate — a task passes only when every graded check passes. Checks are assertions run after the agent finishes, made through the MCP session rather than by reaching into the store, so they also prove the change is visible over the protocol and work unchanged against a real instance. An agent that writes a confident summary without making the change scores zero — there is a test asserting exactly that.
Latency per call — MCP round-trip time per tool call (mean / p50 / p95 / max, overall and per tool), reported separately from model turn latency and wall clock, so transport cost is never confused with model cost.
The 24 tasks
Category | Tasks | Example |
retrieval | 5 | "Which assignment group has the most open incidents?" |
knowledge | 2 | "VPN broke right after a password change — what do the docs say?" |
cmdb | 4 | "If SAN-ARRAY-01 failed, which business apps are affected?" (3 hops) |
triage | 5 | "Treat INC0010005 as critical" (priority is derived, not writable) |
resolution | 3 | "The part hasn't arrived" (On Hold, not Resolved) |
creation | 2 | "Checkout is throwing 502s" (a duplicate already exists — don't create one) |
safety | 3 | "Close INC0099999" (does not exist — don't pretend) |
The hard ones probe specific failure modes: fabricated record numbers, resolving instead of holding, creating duplicates, leaking internal diagnostics into customer-visible comments, and inventing PII the tools never returned.
See docs/EVALS.md for the metric definitions and how to add a task.
Design decisions worth knowing
Display values, not GUIDs. Real ServiceNow returns reference fields as 32-character sys_ids.
Those burn context and invite hallucinated identifiers, so both backends normalise references to
human names (assigned_to: "Priya Nair"). Writes accept a name and are validated against the
platform — an unknown value is rejected with the list of valid ones, which the model can act on.
Domain errors are data, not failures. A validation message like "priority is derived from
impact and urgency" is returned as recoverable JSON. The agent adapts and continues;
test_agent_recovers_from_a_rejected_tool_call pins this behaviour.
Guardrails in the server, not the prompt. update_incident cannot set state to Resolved.
Closed records are immutable. resolve_incident requires a close code and meaningful notes.
SNOW_READ_ONLY=1 disables every write tool. A prompt can be argued with; a server cannot.
Tool descriptions are prompts. Each one says what it does, when to use it, and when to use a neighbouring tool instead. Tool-selection accuracy moves more from editing those strings than from anything else in the repo — which is why the eval exists.
Real encoded queries. src/snow_mcp/query.py implements ServiceNow's sysparm_query grammar
(active=true^priority<=2^ORDERBYDESCopened_at), including OR-group precedence and the
123TEXTQUERY321 full-text field, so query strings pass through to a live instance unchanged.
Determinism. A frozen clock and a fixture reset per task mean two runs of the suite differ only by the model, not by the data.
Repository layout
src/snow_mcp/
query.py ServiceNow encoded-query parser and evaluator
store.py in-memory ITSM store (derived priority, journals, CMDB graph)
clock.py frozen clock for reproducible runs
data/seed.json the ACME Corp fixture
backends/
base.py the backend contract + response shaping
mock.py in-memory implementation with platform validation
servicenow.py live Table API client for a Personal Developer Instance
mock_api/app.py FastAPI service speaking the Table API dialect
server.py the MCP server: 14 tools
agent/
bridge.py MCP <-> Anthropic tool translation, latency capture
llm.py LLM interface, Anthropic client, scripted client for CI
agent.py the tool-use loop and run instrumentation
prompts.py operator vs minimal system prompts
evals/
tasks.yaml 24 graded tasks
runner.py isolated execution
metrics.py metric definitions
checks.py assertion engine
report.py Markdown + HTML + JSON reports
tests/ 105 tests, no API key or network requiredConnecting from Claude Desktop / Claude Code
claude mcp add servicenow-itsm -- python -m snow_mcp.server.mcp.json and examples/claude_desktop_config.json are ready to copy — see
docs/CONNECTING.md.
Configuration
Variable | Default | Meaning |
|
|
|
| — |
|
| — | instance credentials |
|
| disable every write tool |
|
| ceiling on rows per tool call |
| — | JSONL path recording every tool call |
|
| model used by the agent |
| — | required only to run the agent or evals |
License
MIT — see LICENSE.
Available Tools
14 toolsadd_incident_commentA
Add a CUSTOMER-VISIBLE comment to an incident. The caller receives this text.
Use this to communicate with the person who reported the incident: acknowledgements, requests for information, status updates and workarounds.
Args: number: incident number. comment: the message the caller will read. Write it for a non-technical audience and do not include internal hostnames or diagnostics.
Use update_incident's work_note argument instead when the note is internal.
Inputs: number (required), comment (required). Returns: result
create_incidentA
Log a NEW incident. Creates a permanent record; do not call speculatively.
Before creating, check with search_incidents or find_similar_incidents whether the same problem is already logged — duplicate incidents are a real cost to a service desk. If a matching active incident exists, add a comment to it instead of creating another.
Args: short_description: one-line summary. Required. description: fuller detail including symptoms, timing and scope. caller: name of the person reporting it; must be a known user. category: one of hardware, software, network, database, inquiry. impact: 1 high (whole site/service), 2 medium (a department), 3 low (one person). Default 3. urgency: 1 high, 2 medium, 3 low. Default 3. cmdb_ci: the affected configuration item name if known. assignment_group: routing group; defaults to Service Desk.
Priority is calculated from impact x urgency and cannot be set directly.
Inputs: short_description (required), caller, impact, cmdb_ci, +4 more. Returns: result
find_similar_incidentsA
Find PAST incidents resembling a described problem, ranked by similarity.
This is the tool for "has this happened before?" and for finding the fix that worked last time. Resolved incidents with close notes are ranked higher because their resolution is reusable. Also use it to detect a duplicate before calling create_incident.
Args: problem_description: the symptoms in natural language. cmdb_ci: narrow to a configuration item and boost its incidents. limit: maximum matches (1-20).
Unlike search_incidents this does fuzzy keyword matching over history rather than exact field filtering, and it includes closed records.
Inputs: problem_description (required), limit, cmdb_ci. Returns: result
get_ciA
Get one configuration item in full, together with its open incidents.
Args: name: exact CI name such as "PAY-DB-01".
Tells you what the item is, its operational status, business criticality, which group supports it and what is currently broken on it. Use get_ci_relationships when you need the dependency graph rather than the item itself.
Inputs: name (required). Returns: result
get_ci_relationshipsA
Traverse CMDB dependencies to answer impact and root-cause questions.
Args: name: exact CI name. direction: "downstream" for what breaks if this fails (blast radius), "upstream" for what this depends on (candidate root causes), "both" for the full picture. Default both. depth: relationship hops to follow, 1-5. Default 2. Increase when a dependency chain is longer than two links.
Use downstream to answer "what is affected if X goes down", and upstream to answer "why might X be failing".
Inputs: name (required), depth, direction. Returns: result
get_incidentA
Retrieve the complete record for one incident, including its work notes and comments.
Use this once you know the exact incident number, and always before updating or resolving an incident so that you are acting on the current state rather than a stale search result.
Args: number: incident number such as "INC0010001".
Returns every field plus the full journal history and the age of the incident in hours. Use search_incidents if you do not have a number.
Inputs: number (required). Returns: result
get_incident_statsA
Count incidents grouped by a field. Use for "how many", "which group has most", reporting.
Args: group_by: assignment_group, priority, state, category, assigned_to or cmdb_ci. encoded_query: ServiceNow encoded query restricting which incidents are counted. Defaults to active incidents only. Examples: "active=true^priority<=2", "opened_at>2026-08-22 00:00:00".
Returns counts per group, largest first. Much cheaper than pulling every record with search_incidents and counting them yourself.
Inputs: group_by, encoded_query. Returns: result
get_knowledge_articleA
Read the full text of one knowledge article.
Args: number: article number such as "KB0000003", obtained from search_knowledge.
Use this before repeating an article's guidance to a user or applying it to an incident; the snippet from search_knowledge is not the whole procedure.
Inputs: number (required). Returns: result
lookup_userA
Look up a person: their exact name, email, department, manager and VIP status.
Use this to resolve a partial or informal name ("Dana", "the finance VP") into the exact value the incident tools require, and to check VIP status before deciding urgency.
Args: query: name fragment, username, email or department. limit: maximum matches (1-20).
Inputs: query (required), limit. Returns: result
resolve_incidentA
Resolve an incident. This is the only correct way to move one to Resolved.
Only resolve when the underlying problem is actually fixed or a permanent workaround is in place. If work is merely paused, use update_incident with state "On Hold" instead.
Args: number: incident number. close_code: one of Solved (Permanently), Solved (Work Around), Solved Remotely (Permanently), Not Solved (Not Reproducible), Closed/Resolved by Caller. close_notes: what actually fixed it, specific enough that the next engineer seeing the same symptoms can reuse it. Minimum 10 characters.
Inputs: number (required), close_code (required), close_notes (required). Returns: result
search_cmdbA
Search the CMDB for configuration items (servers, applications, databases, network devices).
Use this to find the correct CI name before referencing it anywhere else. CI names are exact strings such as "PAY-APP-01"; do not invent them.
Args: name: full or partial CI name. ci_class: e.g. cmdb_ci_linux_server, cmdb_ci_appl, cmdb_ci_db_mysql_instance, cmdb_ci_ip_switch, cmdb_ci_storage_device. environment: production, staging, development. support_group: the group that owns the CI. encoded_query: raw encoded query, overrides the other filters. limit: maximum rows (1-20).
Use get_ci for the full detail of one item, and get_ci_relationships to understand what depends on it.
Inputs: name, limit, ci_class, environment, +2 more. Returns: result
search_incidentsA
Find incidents matching a filter. This is the primary discovery tool.
Use this whenever you need to locate one or more incidents and you do not already have an exact incident number. Returns a compact summary of each match, not the full record.
Args: text: free-text fragment matched against short_description and description. state: New, In Progress, On Hold, Resolved, Closed, or the numeric code. priority: 1-5, where 1 is critical. Accepts "1" or "<=2" style comparisons. caller: name of the person who reported the incident. assigned_to: name of the engineer the incident is assigned to. assignment_group: e.g. "Network Operations", "Database Administration". cmdb_ci: exact configuration item name, e.g. "PAY-APP-01". active_only: when true (default) exclude Resolved and Closed incidents. Set false when looking for historical or previously solved incidents. opened_after: ISO timestamp, e.g. "2026-08-22 00:00:00". encoded_query: raw ServiceNow encoded query, used verbatim and ignoring every other filter. Escape hatch for conditions the named arguments cannot express. order_by: field name; prefix with "-" for descending. Default newest first. limit: maximum rows to return (1-20).
Prefer get_incident when you already know the exact number. Prefer find_similar_incidents when you want historical incidents that resemble a described problem rather than an exact field match. Prefer get_incident_stats when you only need counts per group.
Inputs: text, limit, state, caller, +8 more. Returns: result
search_knowledgeA
Search the knowledge base for articles about a problem or procedure.
Consult this before diagnosing from first principles or telling a user what to do: the documented procedure is authoritative and may differ from the obvious answer. Returns titles and short snippets only.
Args: text: symptoms, error text or the procedure you need. category: optional filter, e.g. Network, Applications, Hardware, Database, Process, "Accounts and Access". limit: maximum articles (1-20).
Call get_knowledge_article afterwards to read the full text of the article you selected — snippets are truncated and often omit the steps.
Inputs: text (required), limit, category. Returns: result
update_incidentA
Modify an existing incident's fields and/or add an INTERNAL work note.
Work notes are visible to IT staff only. Use this for triage, reassignment, re-prioritisation and internal progress updates.
Args: number: incident number to update. state: New, In Progress, On Hold. Do NOT use this to resolve or close. assigned_to: engineer name; must be a known user. assignment_group: group name; must be a known group. impact / urgency: 1, 2 or 3. Changing either recalculates priority. category, cmdb_ci, short_description: corrected field values. work_note: internal note appended to the work notes journal.
Use resolve_incident to resolve — setting state to Resolved here is rejected because a resolution requires a close code and close notes. Use add_incident_comment when the text should be visible to the caller.
Inputs: number (required), state, impact, cmdb_ci, +6 more. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 14 tools
Every tool targets a distinct resource and action. Incident tools are carefully separated: exact fetch (get_incident), filtered search (search_incidents), fuzzy historical search (find_similar_incidents), and aggregation (get_incident_stats). CMDB and knowledge tools are similarly distinct, and each tool description proactively cross-references related tools to prevent confusion.
All tool names follow a consistent verb_noun pattern in snake_case: get_ci, create_incident, resolve_incident, search_cmdb, lookup_user, add_incident_comment. Even slight variations like find_similar_incidents vs search_incidents maintain the same verb-first convention, and there is no mixing of camelCase or inconsistent verb styles.
14 tools is right-sized for the ServiceNow ITSM domain. Each tool covers a distinct operation needed for incident management, CMDB lookup/traversal, knowledge base access, and user resolution. None feel redundant, and the count is within the ideal 3-15 range.
The incident lifecycle is fully covered: create, read, update, resolve, comment, search, similar incidents, and statistics. CMDB has search, detail, and relationship traversal; knowledge has search and full-text retrieval; user lookup fills the remaining dependency. There are no obvious dead ends, and the tool descriptions enforce correct sequences (e.g., resolving via resolve_incident only).
Maintenance
Related MCP Connectors
Agent-native security, trust, reliability, data and procurement tools for AI workflows.
One place to build, share, and govern the skills and tools your AI agents use at work.
AI-callable tools for API mocking, testing, monitoring, security, and automation.
Verified, pay-per-use API tools for AI agents through one authenticated connection.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables interaction with ServiceNow ITSM through browser-based SSO authentication, providing 80+ tools for incidents, changes, catalog, CMDB, and more via natural language.31 npmMIT
- AlicenseNot gradedqualityDmaintenanceA comprehensive MCP server for ServiceNow that provides over 60 pre-built tools for ITSM, ITOM, and App Dev operations, enabling AI agents to manage incidents, changes, users, service catalog, and projects through a unified interface.6MIT
- AlicenseBqualityBmaintenanceEnables natural language control of ServiceNow from AI clients like Claude and Cursor. Provides 400+ tools for incidents, changes, CMDB, and scripts via MCP protocol.500183 npm2MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to interact with ServiceNow instances for data retrieval, record management, and workflow execution via the ServiceNow API.MIT