# Mcp Server Servicenow

> MCP server from pavecer/mcp-server-servicenow.

- **Type:** MCP server
- **Install:** `agentstack add mcp-pavecer-mcp-server-servicenow`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [pavecer](https://agentstack.voostack.com/s/pavecer)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [pavecer](https://github.com/pavecer)
- **Source:** https://github.com/pavecer/mcp-server-servicenow

## Install

```sh
agentstack add mcp-pavecer-mcp-server-servicenow
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# ServiceNow MCP Server

A stateless [Model Context Protocol](https://modelcontextprotocol.io) server for ServiceNow Service Catalog, hosted on Azure Functions. It connects Microsoft Copilot Studio to ServiceNow so users can search catalog items, fill order forms rendered as Adaptive Cards, and place orders from within a Copilot Studio agent.

**MCP tools provided:**

| Tool | Description |
|------|-------------|
| `search_catalog_items` | Full-text catalog search with Adaptive Card item picker |
| `get_catalog_item_form` | Returns an Adaptive Card form for the selected item |
| `place_order` | Submits the order and returns a confirmation Adaptive Card |
| `list_user_orders` | Lists the caller's open (non-closed) catalog orders, enriched with their request items |
| `update_order` | Updates a small allowlist of requestor-mutable fields on the caller's order (`short_description`, `description`, `comments`, `urgency`, `priority`) |
| `validate_servicenow_config` | Validates OAuth and catalog API access end-to-end |

**Related documentation:**

- [Copilot Studio Setup](COPILOT_STUDIO_SETUP.md) -- add MCP tool and configure ordering topic
- [Copilot Studio reference agents](copilot-studio/README.md) -- how this MCP server fits the ESS IT / ESS ServiceNow Catalog agent architecture
- [Why not the MCP wizard? Use a custom connector for SSO/OBO](docs/WHY_CUSTOM_MCP_CONNECTOR.md) -- why the auto-provisioned MCP connector cannot do silent SSO, and what to do instead (Teams + M365 Copilot)
- [Custom MCP Connector with OBO / SSO](docs/CUSTOM_MCP_CONNECTOR_OBO.md) -- hand-author a custom MCP connector so users get true silent SSO instead of the per-user "Open connection manager" prompt
- [Cost Estimation](docs/COST_ESTIMATION.md) -- Azure infrastructure + Copilot Studio message consumption cost model, per-operation pricing, and worked examples for pilot / SMB / enterprise scenarios
- [Agent 365 BYO MCP](docs/AGENT_365_BYO_MCP.md) -- register this server in the Microsoft 365 admin center for tenant-wide governance
- [ServiceNow Setup](docs/SERVICENOW_SETUP.md) -- OAuth app, integration user, and permissions
- [Action Contracts](docs/MCS_ACTION_CONTRACTS.md) -- tool schemas for Copilot Studio topic authors
- [Optional Container Deployment](docs/DEPLOY_CONTAINER_AZURE.md) -- run as one Docker container in Azure Container Apps
- [Security Guidelines](SECURITY.md) -- what to never commit

---

## Prerequisites

| Requirement | Notes |
|-------------|-------|
| Azure subscription | Permission to create resource groups and Entra app registrations |
| Azure CLI (az) | [Install guide](https://learn.microsoft.com/cli/azure/install-azure-cli) |
| Azure Developer CLI (azd) | [Install guide](https://learn.microsoft.com/azure/developer/azure-developer-cli/install-azd) |
| Node.js 20+ | To build the project locally |
| ServiceNow instance | Admin access to create OAuth apps and users |
| Microsoft Entra ID | Permission to register an app |
| Copilot Studio agent model | **GPT-5 or newer**, or **Claude Sonnet**. **GPT-4.1 is not supported** because it does not render the MCP Adaptive Cards. See [COPILOT_STUDIO_SETUP.md](COPILOT_STUDIO_SETUP.md#supported-orchestrator-models). |

---

## Quick Start

### Step 1 -- Set up ServiceNow

See [docs/SERVICENOW_SETUP.md](docs/SERVICENOW_SETUP.md) for the complete guide, or run the automation script:

```powershell
pwsh -File scripts/setup-servicenow.ps1 \
  -InstanceUrl https://.service-now.com \
  -AdminUser  \
  -AdminPassword 
```

What you need from ServiceNow:
- **Client ID** and **Client Secret** from the OAuth App Registry entry
- **Integration user** username and password (with `catalog` role)

---

### Step 2 -- Register an Entra ID Application

This enables per-user OAuth 2.0 authentication in Copilot Studio.

1. [Azure Portal](https://portal.azure.com) > **Entra ID > App registrations > New registration**
   - Name: `ServiceNow MCP Server`
   - Supported account types: `Accounts in this organizational directory only`
   - Click **Register**
   - Note **Application (client) ID** = `ENTRA_CLIENT_ID`
   - Note **Directory (tenant) ID** = `ENTRA_TENANT_ID`

2. **Certificates & secrets > New client secret** -- copy the value immediately = `ENTRA_CLIENT_SECRET`

3. **Expose an API > Set** Application ID URI -- accept default `api://`
   - **Add a scope**: name `access_as_user`, consent: Admins and users

4. **Authentication > Add a platform > Web** -- add redirect URIs:
   ```
   https://oauth.botframework.com/callback
   https://global.consent.azure-apim.net/redirect
   https://copilotstudio.preview.microsoft.com/connection/oauth/redirect
   ```
   Enable **Access tokens** and **ID tokens** > **Save**

5. *(Recommended)* **API permissions > Add > My APIs > ServiceNow MCP Server** > `access_as_user` > **Grant admin consent**
   This lets all tenant users use the agent without individual consent prompts.

---

### Step 3 -- Deploy to Azure

**Interactive (recommended for first deployment):**

```powershell
npm run deploy:azure
```

The script prompts for all values, provisions Azure resources (Function App, Key Vault, Application Insights), deploys the function, and prints Copilot Studio setup instructions.

**Non-interactive (CI/CD):**

```powershell
pwsh -File scripts/deploy-azure.ps1 \
  -EnvironmentName prod \
  -Location westeurope \
  -SubscriptionId  \
  -ServiceNowInstanceUrl https://.service-now.com \
  -ServiceNowClientId  \
  -ServiceNowClientSecret  \
  -ServiceNowUsername  \
  -ServiceNowPassword  \
  -EntraTenantId  \
  -EntraClientId  \
  -EntraClientSecret 
```

**Manual azd:**

```bash
az login && azd auth login
azd env new 
azd env set SERVICENOW_INSTANCE_URL  "https://.service-now.com"
azd env set SERVICENOW_CLIENT_ID     ""
azd env set SERVICENOW_CLIENT_SECRET ""
azd env set SERVICENOW_USERNAME      ""
azd env set SERVICENOW_PASSWORD      ""
azd env set ENTRA_TENANT_ID          ""
azd env set ENTRA_CLIENT_ID          ""
azd env set ENTRA_CLIENT_SECRET      ""
azd up
```

Get the deployed MCP endpoint URL:

```bash
azd env get-values | findstr MCP_ENDPOINT_URL
```

### Optional: Deploy as One Container (Azure Container Apps)

If you prefer a single container deployment instead of Azure Functions, use the Docker + Container Apps path documented in [docs/DEPLOY_CONTAINER_AZURE.md](docs/DEPLOY_CONTAINER_AZURE.md).

This path builds this repo as a single Node.js container and exposes the same MCP endpoint shape at `/mcp`.

---

### Step 4 -- Add to Microsoft Copilot Studio

See [COPILOT_STUDIO_SETUP.md](COPILOT_STUDIO_SETUP.md) for the full guide.

1. Copilot Studio > your agent > **Tools > Add a tool > Model Context Protocol**
2. Fill in:

   | Field | Value |
   |-------|-------|
   | Server name | `ServiceNow MCP` |
   | Server URL | `https://.azurewebsites.net/mcp` |
   | Authentication | `OAuth 2.0` |
   | Type | `Dynamic discovery` |

3. Click **Create** > sign in when prompted > verify all 4 tools appear.
4. Import the ordering topic from `copilot-studio/topics/` into your agent.

---

### Step 5 -- (Optional) Register with Microsoft Agent 365 (BYO MCP)

To make this MCP server tenant-governed (visible in **Microsoft 365 admin center > Agents > Tools > Registry**, monitored in Defender XDR, and discoverable from Copilot Studio, VS Code, Claude Code, and GitHub Copilot CLI), register it as a Bring-Your-Own MCP server with [Microsoft Agent 365](https://learn.microsoft.com/en-us/microsoft-365/admin/manage/manage-tools-for-agent?view=o365-worldwide#bring-your-own-byo-mcp-server).

The server already speaks `EntraOAuth` end-to-end, so no code changes are required. Use the helper script:

```powershell
pwsh -File scripts/register-agent365-mcp.ps1 `
  -ServerName     "ext_ServiceNowMCP" `
  -PublisherName  "" `
  -McpEndpointUrl "https://.azurewebsites.net/mcp" `
  -EntraClientId  "" `
  -TenantId       ""
```

> The CLI requires the server name to start with `ext_` and be ≤ 20 characters.

A tenant admin (Global admin or AI admin) then approves the request in the Microsoft 365 admin center. Full step-by-step guide, troubleshooting, and Defender hunting query: [docs/AGENT_365_BYO_MCP.md](docs/AGENT_365_BYO_MCP.md).

---

## Architecture

- **Runtime**: Azure Functions v4, Node.js 20, Flex Consumption (FC1)
- **Transport**: Streamable HTTP, stateless MCP
- **MCP auth**: OAuth 2.0 via Microsoft Entra ID (per-user sign-in)
- **ServiceNow auth**: OAuth 2.0 password grant with a shared integration user
- **Secrets**: All secrets in Azure Key Vault; Function App reads via managed identity
- **Monitoring**: Application Insights

### HTTP surfaces and authentication

The deployed Function App exposes the routes below. Auth requirements are
fixed in code; no extra Function-level keys, network ACLs, or RBAC are
applied beyond what's documented here.

| Method · Route | Purpose | Auth |
|---|---|---|
| `POST /mcp` | MCP Streamable HTTP — `tools/list`, `tools/call` | **Entra Bearer required** (validated by [src/utils/entraAuthMiddleware.ts](src/utils/entraAuthMiddleware.ts)) |
| `GET /mcp` | SSE readiness probe (Streamable HTTP transport) | Anonymous |
| `DELETE /mcp` | Session cleanup (stateless mode no-op) | Anonymous |
| `OPTIONS /mcp` | CORS preflight | Anonymous |
| `POST /api/catalog/search` · `GET /api/catalog/form/:sysId` · `POST /api/catalog/order` | Deterministic REST surface for Copilot Studio topics | **Entra Bearer required** |
| `OPTIONS /api/catalog/*` | CORS preflight | Anonymous |
| `GET /health` | Liveness/readiness probe — returns `{"status":"ok","server":"servicenow-mcp"}` | Anonymous |
| `GET /.well-known/openid-configuration` · `oauth-authorization-server` · `oauth-protected-resource` | OIDC discovery and RFC 8414/9728 metadata | Anonymous |
| `POST /oauth/register` | RFC 7591 Dynamic Client Registration | Gated — see below |
| `GET /oauth/register` | Lightweight capability doc for clients that probe before POST | Anonymous |

`POST /oauth/register` is **closed by default**: when no `ENTRA_DCR_REGISTRATION_TOKEN` is set and `ENTRA_DCR_ALLOW_UNAUTHENTICATED` is not `"true"`, the endpoint returns **403**. With a registration token configured the request must include `Authorization: Bearer ` (constant-time comparison); set `ENTRA_DCR_ALLOW_UNAUTHENTICATED=true` to opt in to anonymous DCR.

When `ENTRA_AUTH_DISABLED=true` (intended for local dev only), Bearer validation is bypassed on `POST /mcp` and `/api/catalog/*`. The startup log emits a `WARN` line stating the effective tenant policy at every cold start so this is visible in App Insights.

### Delegated Identity Flow

Each order is correctly attributed to the Copilot Studio user who placed it:

1. Copilot Studio sends the user's Entra Bearer token to the MCP server.
2. The MCP server validates the token and extracts the caller's UPN/email.
3. The server obtains a ServiceNow token for the integration user (password grant).
4. The caller's email is looked up in `sys_user` to find their ServiceNow `sys_id`.
5. The order is placed, then immediately PATCHed to set `requested_for` to the resolved user.

> **Integration user permissions needed**: read on `sys_user`, read+write on `sc_request`, plus `catalog` and/or `itil` roles.

---

## Local Development

```bash
npm install
cp local.settings.sample.json local.settings.json
# Edit local.settings.json -- ENTRA_AUTH_DISABLED is true by default for local use
npm run start:dev
```

MCP endpoint: `http://localhost:7071/mcp`

```bash
# Smoke test against local
set MCP_ENDPOINT_URL=http://localhost:7071/mcp
npm run smoke:test
```

---

## Environment Variables Reference

### Required

| Variable | Description |
|----------|-------------|
| `SERVICENOW_INSTANCE_URL` | ServiceNow base URL (`https://instance.service-now.com`) |
| `SERVICENOW_CLIENT_ID` | OAuth App Registry client ID |
| `SERVICENOW_CLIENT_SECRET` | OAuth App Registry client secret |
| `SERVICENOW_USERNAME` | Integration user login |
| `SERVICENOW_PASSWORD` | Integration user password |

### Entra ID (required for Copilot Studio OAuth)

| Variable | Description |
|----------|-------------|
| `ENTRA_TENANT_ID` | Entra directory (tenant) ID |
| `ENTRA_CLIENT_ID` | App registration client ID |
| `ENTRA_CLIENT_SECRET` | App registration client secret (for Dynamic Client Registration) |
| `ENTRA_AUDIENCE` | Expected `aud` in tokens; defaults to `api://` |

### Optional

| Variable | Default | Description |
|----------|---------|-------------|
| `ENTRA_AUTH_DISABLED` | `false` | Skip Bearer validation -- local dev only, never in production |
| `ENTRA_OAUTH_SCOPES` | `api:///access_as_user openid profile offline_access` | Scopes advertised in OIDC discovery |
| `ENTRA_TRUSTED_TENANT_IDS` | _(empty)_ | Accepted remote tenant IDs (multi-tenant scenarios) |
| `ENTRA_ALLOW_ANY_TENANT` | `false` | Accept any Microsoft tenant token |
| `ENTRA_DCR_REGISTRATION_TOKEN` | _(unset)_ | Bearer token required on `POST /oauth/register` |
| `ENTRA_DCR_ALLOW_UNAUTHENTICATED` | `false` | Allow open Dynamic Client Registration when no token is configured |
| `ENTRA_ALLOWED_AUDIENCES` | _(empty)_ | Comma-separated extra `aud` values to accept (custom App ID URIs) |
| `CORS_ALLOWED_ORIGINS` | _(empty)_ | Comma-separated browser origins for CORS-enabled endpoints |
| `SERVICENOW_OAUTH_TOKEN_PATH` | `/oauth_token.do` | ServiceNow token endpoint path |
| `SERVICENOW_OAUTH_GRANT_TYPE` | `auto` | Override grant type: `password` or `client_credentials` |
| `SERVICENOW_OAUTH_CLIENT_AUTH_STYLE` | `auto` | OAuth client auth style: `request_body` or `basic` |
| `SERVICENOW_REQUIRE_CALLER_ACCESS_TOKEN` | `false` | When `true`, refuse calls without `x-servicenow-access-token` (per-user ACL enforcement) |
| `SERVICENOW_REQUESTED_FOR_LOOKUP_FIELDS` | `email,user_name` | `sys_user` fields for identity resolution |
| `SERVICENOW_REQUESTED_FOR_CALLER_FIELDS` | `callerUpn` | Entra token claims to use as identity source |
| `SERVICENOW_REQUESTED_FOR_FALLBACK_TO_CALLER_VALUE` | `true` | Fall back to UPN if no `sys_user` match |
| `SERVICENOW_REQUESTED_FOR_DIAGNOSTICS` | `false` | Include requested_for diagnostics in tool/API responses |
| `SERVICENOW_REQUESTED_FOR_DIAGNOSTICS_INCLUDE_PII` | `false` | Include raw caller identifiers in diagnostics (for short-lived troubleshooting only) |
| `LOG_LEVEL` | `info` | Minimum log level emitted to stdout: `debug`, `info`, `warn`, or `error` |
| `LOG_INCLUDE_CALLER_IDENTITY` | `false` | Attach caller `oid`/`upn` to every log entry. Off by default to keep PII out of App Insights |
| `LOG_INCLUDE_ERROR_STACK` | `false` | Include error stack traces in error log entries |

---

## Local Testing Against ServiceNow

Two ways to verify ServiceNow responses without going through Copilot Studio:

### Option A — Run the full MCP server locally and call it via JSON-RPC

```powershell
# 1. Copy the sample settings file and fill in your ServiceNow credentials.
Copy-Item local.settings.sample.json local.settings.json
#    Set SERVICENOW_INSTANCE_URL / SERVICENOW_CLIENT_ID / SERVICENOW_CLIENT_SECRET
#    (and SERVICENOW_USERNAME / SERVICENOW_PASSWORD for the password grant).
#    ENTRA_AUTH_DISABLED=true is the default in the sample so no Bearer token is needed.

# 2. Start the function locally on http://localhost:7071/mcp
npm run start:dev

# 3. In a second terminal, run the MCP smoke test against localhost.
$env:MCP_ENDPOINT_URL = "http://localhost:7071/mcp"
$env:SEARCH_QUERY = "laptop"
npm run smoke:test
```

This exercises the full request pipeline (Express, MCP SDK, Streamable HTTP transport, `ServiceNowClient`).

### Option B — Direct ServiceNow probe (no MCP, no Functions runtime)

For faster iteration when you only care about ServiceNow responses, the
`scripts/dev/test-servicenow-local.mjs` runner loads `local.settings.json`
and calls the `ServiceNowClient` methods directly:

```powershell
npm run sn:local -- validate
npm run sn:local -- search "vpn access" 5
npm run sn:local -- form 04b7e94b4f7b4200086eeed18110c

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [pavecer](https://github.com/pavecer)
- **Source:** [pavecer/mcp-server-servicenow](https://github.com/pavecer/mcp-server-servicenow)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** yes
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-pavecer-mcp-server-servicenow
- Seller: https://agentstack.voostack.com/s/pavecer
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.