ServiceNow MCP Demo — Asistente de Incidentes

Una demo de Model Context Protocol de extremo a extremo que conecta Claude con ServiceNow Incident Management. Construida para mostrar los fundamentos de MCP (servidores, clientes, herramientas, recursos, transporte stdio, bucles de agente) aplicados a un flujo de trabajo ITSM real.

Arquitectura

┌─────────────────────────────┐        ┌───────────────────────────────┐        ┌────────────────┐
│  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           │        │                │
└─────────────────────────────┘        └───────────────────────────────┘        └────────────────┘

Flujo para "mi portátil no arranca, abre un ticket":

1. El cliente web envía tu mensaje a Claude junto con los esquemas de herramientas que descubrió del servidor MCP al inicio (tools/list).

2. Claude decide llamar a create_incident con urgencia/impacto/categoría inferidos.

3. El cliente reenvía la llamada a través de MCP (tools/call); el servidor accede a la API de Tablas de ServiceNow (o al mock en memoria).

4. El resultado regresa; Claude confirma el número de incidente; la interfaz renderiza una tarjeta de incidente.

Related MCP server: ServiceNow MCP Server (SSE)

Inicio rápido

# 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

Abre http://localhost:8501 y prueba:

• "Mi portátil no arranca y tengo una demo de cliente en una hora — abre un ticket."

• "Muéstrame los 5 incidentes más recientes."

• "Mueve INC0010001 a En Progreso con una nota de trabajo de que el técnico está en camino."

• "¿Hay artículos de KB sobre un portátil que no enciende?"

• "Eso lo arregló — resuelve INC0010001, resuelto permanentemente, reemplazó el cargador."

Modo ServiceNow en vivo

1. Solicita una Instancia Personal de Desarrollador (PDI) gratuita en https://developer.servicenow.com (tarda ~2 minutos).

2. En .env, establece SERVICENOW_MODE=live y completa SERVICENOW_INSTANCE, SERVICENOW_USER, SERVICENOW_PASSWORD.

3. Reinicia la aplicación. Los incidentes creados aparecerán en tu PDI bajo Incident > All — ideal para mostrar el ticket en la interfaz real de ServiceNow durante la demo.

Las PDI hibernan tras inactividad. Despierta la tuya ~15 minutos antes de tu entrevista y mantén el modo mock como respaldo.

search_knowledge_articles consulta directamente la tabla kb_knowledge de la PDI — antes de hacer la demo en modo en vivo, siembra 2–3 artículos de KB publicados allí con títulos que coincidan con tu escenario de demo (p. ej., "El portátil no enciende"), o la búsqueda en vivo volverá vacía. El modo mock ya incluye 3 artículos sembrados, así que funciona de fábrica.

Probando el servidor de forma independiente (sin interfaz)

El MCP Inspector es la forma más rápida de comprobar que el servidor funciona por sí solo:

npx @modelcontextprotocol/inspector python server/servicenow_server.py

También puedes añadir el servidor a Claude Desktop (claude_desktop_config.json):

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

Estructura del proyecto

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

Conceptos de MCP demostrados

• Servidor construido con FastMCP: herramientas con parámetros tipados y esquemas basados en docstrings

• Recurso (servicenow://reference/priority-matrix) — contexto de solo lectura, distinto de las herramientas

• Transporte stdio — el cliente lanza el subproceso del servidor y habla JSON-RPC

• Descubrimiento de capacidades — el cliente nunca codifica herramientas; llama a tools/list

• Bucle de agente — uso de herramientas en múltiples rondas con Claude hasta una respuesta de texto final

• Separación de preocupaciones — el mismo servidor funciona con este cliente web, Claude Desktop o MCP Inspector, sin cambios