ServiceNow MCP Demo — Incident Assistant

An end-to-end Model Context Protocol demo that connects Claude to ServiceNow Incident Management. Built to showcase MCP fundamentals (servers, clients, tools, resources, stdio transport, agent loops) applied to a real ITSM workflow.

Architecture

┌─────────────────────────────┐        ┌───────────────────────────────┐        ┌────────────────┐
│  Web Client (Streamlit)     │  MCP   │  MCP Server (FastMCP)         │  REST  │  ServiceNow    │
│  - MCP host + client        │◄──────►│  - create_incident            │◄──────►│  Table API     │
│  - Claude agent loop        │ stdio  │  - get_incident               │        │  (or mock mode)│
│  - Incident cards in UI     │JSON-RPC│  - list_recent_incidents      │        │                │
│                             │        │  - update_incident_state      │        │                │
│                             │        │  - resolve_incident           │        │                │
│                             │        │  - search_knowledge_articles  │        │                │
│                             │        │  - resource: priority         │        │                │
│                             │        │    matrix reference           │        │                │
└─────────────────────────────┘        └───────────────────────────────┘        └────────────────┘

Flow for "my laptop won't boot, open a ticket":

1. The web client sends your message to Claude along with the tool schemas it discovered from the MCP server at startup (tools/list).

2. Claude decides to call create_incident with inferred urgency/impact/category.

3. The client forwards the call over MCP (tools/call); the server hits the ServiceNow Table API (or the in-memory mock).

4. The result flows back; Claude confirms the incident number; the UI renders an incident card.

Related MCP server: ServiceNow MCP Server (SSE)

Quick start

# 1. Create a virtual environment
python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate

# 2. Install dependencies
pip install -r requirements.txt

# 3. Configure
cp .env.example .env             # then edit: add your ANTHROPIC_API_KEY
                                 # leave SERVICENOW_MODE=mock for a no-setup demo

# 4. Run the web client (it launches the MCP server automatically)
streamlit run client/app.py

Open http://localhost:8501 and try:

• "My laptop won't boot and I have a client demo in an hour — open a ticket."

• "Show me the 5 most recent incidents."

• "Move INC0010001 to In Progress with a work note that the tech is en route."

• "Any KB articles on a laptop that won't power on?"

• "That fixed it — resolve INC0010001, solved permanently, replaced the charger."

Live ServiceNow mode

1. Request a free Personal Developer Instance (PDI) at https://developer.servicenow.com (takes ~2 minutes).

2. In .env, set SERVICENOW_MODE=live and fill in SERVICENOW_INSTANCE, SERVICENOW_USER, SERVICENOW_PASSWORD.

3. Restart the app. Created incidents will appear in your PDI under Incident > All — great for showing the ticket in the real ServiceNow UI during the demo.

PDIs hibernate after inactivity. Wake yours up ~15 minutes before your interview, and keep mock mode as a fallback.

search_knowledge_articles queries the PDI's kb_knowledge table directly — before demoing in live mode, seed 2–3 published KB articles there with titles matching your demo scenario (e.g. "Laptop won't power on"), or the live search will come back empty. Mock mode already ships with 3 seeded articles so it works out of the box.

Testing the server standalone (no UI)

The MCP Inspector is the fastest way to prove the server works on its own:

npx @modelcontextprotocol/inspector python server/servicenow_server.py

You can also add the server to Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "servicenow": {
      "command": "python",
      "args": ["/absolute/path/to/server/servicenow_server.py"]
    }
  }
}

Project layout

servicenow-mcp-demo/
├── server/servicenow_server.py   # FastMCP server: 6 tools + 1 resource, mock/live backends
├── client/app.py                 # Streamlit web app: MCP client + Claude agent loop
├── requirements.txt
├── .env.example
├── PROJECT_PLAN.md               # Phase-by-phase build plan and status
└── DEMO_SCRIPT.md                # 5-minute recorded-demo script

MCP concepts demonstrated

• Server built with FastMCP: tools with typed parameters and docstring-driven schemas

• Resource (servicenow://reference/priority-matrix) — read-only context, distinct from tools

• stdio transport — client launches the server subprocess and speaks JSON-RPC

• Capability discovery — the client never hardcodes tools; it calls tools/list

• Agent loop — multi-round tool use with Claude until a final text answer

• Separation of concerns — the same server works with this web client, Claude Desktop, or MCP Inspector, unchanged