Skip to main content
Glama
servicenow-mcp-agent

servicenow-mcp-agent

by Sourolio10

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

search_incidents

Primary discovery; named filters or a raw encoded query

get_incident

One full record including work notes and comments

create_incident

Log a new incident (validated references, derived priority)

update_incident

Field changes and internal work notes

add_incident_comment

Customer-visible comment

resolve_incident

The only path to Resolved; requires close code + notes

find_similar_incidents

Fuzzy history search — "has this happened before?"

get_incident_stats

Grouped counts without pulling every record

search_knowledge / get_knowledge_article

KB search, then full text

search_cmdb / get_ci

Find configuration items; one CI plus its open incidents

get_ci_relationships

Dependency graph: upstream causes, downstream blast radius

lookup_user

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 gate

Outputs 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 required

Connecting 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

SNOW_BACKEND

mock

mock or servicenow

SNOW_INSTANCE_URL

—

https://devXXXXX.service-now.com

SNOW_USERNAME / SNOW_PASSWORD

—

instance credentials

SNOW_READ_ONLY

0

disable every write tool

SNOW_MAX_RESULTS

20

ceiling on rows per tool call

SNOW_AUDIT_LOG

—

JSONL path recording every tool call

SNOW_AGENT_MODEL

claude-sonnet-5

model used by the agent

ANTHROPIC_API_KEY

—

required only to run the agent or evals

License

MIT — see LICENSE.

Available Tools

14 tools
add_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

    A4.7/5.0

    Scored across 14 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness5/5

    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

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers