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 │        │                │
│                             │        │  - 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.

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."

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.

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: 4 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