Mcp Server Servicenow

ServiceNow MCP Server

A stateless Model Context Protocol 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](COPILOTSTUDIOSETUP.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/WHYCUSTOMMCP_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/CUSTOMMCPCONNECTOR_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/AGENT365BYO_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/MCSACTIONCONTRACTS.md) -- tool schemas for Copilot Studio topic authors
• [Optional Container Deployment](docs/DEPLOYCONTAINERAZURE.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 | | Azure Developer CLI (azd) | Install guide | | 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 [COPILOTSTUDIOSETUP.md](COPILOTSTUDIOSETUP.md#supported-orchestrator-models). |

---

Quick Start

Step 1 -- Set up ServiceNow

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

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

1. Certificates & secrets > New client secret -- copy the value immediately = ENTRA_CLIENT_SECRET

1. Expose an API > Set Application ID URI -- accept default api://

• Add a scope: name access_as_user, consent: Admins and users

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

1. (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):

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

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:

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:

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/DEPLOYCONTAINERAZURE.md](docs/DEPLOYCONTAINERAZURE.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 [COPILOTSTUDIOSETUP.md](COPILOTSTUDIOSETUP.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 |

1. Click Create > sign in when prompted > verify all 4 tools appear.
2. 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.

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

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/AGENT365BYOMCP.md](docs/AGENT365BYOMCP.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

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

# 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

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

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.