# ServiceNow MCP Server

A self-hosted [Model Context Protocol](https://modelcontextprotocol.io) server that exposes a
**ServiceNow** instance to MCP clients such as **Microsoft Copilot Studio** (and any other MCP
client, e.g. Claude). It runs entirely on **standard ServiceNow licensing** by calling the
platform's REST APIs (Table / Aggregate / CMDB), and uses **per-user OAuth 2.0 token
passthrough** so every call runs as the signed-in user with their own ACLs enforced.

## Why this exists

The target instance is on a standard ServiceNow license, so ServiceNow's native MCP Server
Console (Now Assist / AI Native SKU only) is unavailable. This server is a portable, reusable
integration layer — one MCP server, usable across clients and across AI front-ends — instead of
a Copilot-Studio-specific connector.

## How auth works (token passthrough)

```
User ⇄ Copilot Studio  --(per-user OAuth: ServiceNow access token as Bearer)-->  this server
                                                       │ forwards the same Bearer token
                                                       ▼
                                          ServiceNow REST APIs (ACLs enforced as that user)
```

The server stores **no** user credentials. It reads the incoming `Authorization: Bearer <token>`
header and forwards it verbatim to ServiceNow. See [`auth.py`](src/servicenow_mcp/auth.py).

## Tools

**Tier 1 — direct retrieval (read-only):**
`get_incident`, `list_incidents`, `get_change_request`, `list_change_requests`,
`get_service_request`, `list_service_requests`, `get_configuration_item`,
`find_configuration_items`, `search_knowledge`, `get_knowledge_article`, `lookup_user`,
`lookup_group`.

**Tier 2 — deterministic logic:**
`correlate_changes_to_incident`, `get_incident_trends`, `get_ci_impact`,
`find_similar_incidents`, `get_incident_context`.

Root-cause analysis and final similar-incident ranking are intentionally left to the agent's
reasoning, fed by `get_incident_context` / `find_similar_incidents`.

**Write tools (incidents only, confirm-gated):**
`create_incident`, `update_incident`, `add_work_note`. Every read tool is marked
`readOnlyHint=true` in its MCP annotations (so MCP clients that respect the hint, e.g. Microsoft
365 Copilot, never prompt for confirmation on a lookup); the write tools omit that hint so
compliant clients *do* prompt. That client-side behavior isn't relied on alone, though — each
write tool also defaults to `confirm=false`, in which case it returns a **preview** of the exact
fields it would write without contacting ServiceNow at all. Only a call with `confirm=true`
actually performs the write. This makes the safety belt-and-suspenders and independent of which
MCP client is calling, consistent with this server being client-agnostic. See
[`tools/common.py`](src/servicenow_mcp/tools/common.py)'s `preview()` and
[`tools/incidents.py`](src/servicenow_mcp/tools/incidents.py).

## Run locally

```bash
python -m venv .venv
.venv/Scripts/pip install -e ".[dev]"      # Windows; use .venv/bin on macOS/Linux
cp .env.example .env                        # set SERVICENOW_INSTANCE_URL
SERVICENOW_INSTANCE_URL=https://devXXXXX.service-now.com .venv/Scripts/servicenow-mcp
```

The server listens on `http://HOST:PORT/mcp` (Streamable HTTP) with a `/health` probe.

### Inspect with MCP Inspector

```bash
npx @modelcontextprotocol/inspector
```

Point it at `http://localhost:8000/mcp`, choose Streamable HTTP, and supply a ServiceNow OAuth
access token as the Bearer token to exercise the tools. This is the closest MCP equivalent to a
Swagger UI: it lists every tool with its schema and lets you call each one interactively.

### List all tools (no server or ServiceNow connection needed)

```bash
.venv/Scripts/python scripts/list_tools.py         # human-readable catalog
.venv/Scripts/python scripts/list_tools.py --json   # machine-readable (like an OpenAPI dump)
```

## Deploy

Container image + Azure Container Apps. See [`docs/DEPLOYMENT.md`](docs/DEPLOYMENT.md) for the
ServiceNow OAuth app registration, Copilot Studio wiring, and infra.

For a full click-by-click walkthrough — including exposing a local server via a dev tunnel,
creating the agent from scratch, and the two-user ACL test — see
[`docs/COPILOT_STUDIO_SETUP.md`](docs/COPILOT_STUDIO_SETUP.md).

## Tests

```bash
.venv/Scripts/pytest
```