Secure Delegated ServiceNow MCP Runtime

A secure MCP runtime on Google Cloud Run that enables a ServiceNow AI Agent to access another ServiceNow instance as the signed-in user—using delegated OAuth, least-privilege scopes, Dynamic Me filtering, Cloud KMS encryption, and rotating refresh tokens.

Status: Completed · End-to-end validated with ServiceNow Agent Studio<br> Stack: TypeScript · Node.js · MCP · ServiceNow · Cloud Run · Firestore · Cloud KMS<br> Validation: 79 automated tests passing

Architecture

flowchart LR
    A["ServiceNow AI Agent<br/>MCP Client"]
    B["Secure MCP Runtime<br/>Google Cloud Run"]
    C["ServiceNow Resource Instance<br/>Delegated User Context"]
    D[("Firestore<br/>Sessions & Token Hashes")]
    E["Cloud KMS<br/>Encrypted Delegated Tokens"]

    A -->|"OAuth + PKCE<br/>MCP tools"| B
    B -->|"Delegated user bearer<br/>Allowlisted API queries"| C
    B --> D
    B --> E

The MCP bearer authenticates the client to this runtime and is never sent to ServiceNow. A separate delegated bearer represents the signed-in user to the ServiceNow resource instance, where Dynamic Me and ACLs enforce user-level access.

What this project demonstrates

• Delegated identity across two ServiceNow instances.
• An enterprise MCP client/server integration with ServiceNow Agent Studio.
• Separation between the MCP client bearer and the downstream user bearer.
• Least-privilege tool scopes and server-owned query construction.
• Secure token storage, rotation, replay detection, and session revocation.
• Cloud-native deployment and automated validation on Google Cloud.

Demo

The MCP server was authenticated from ServiceNow Agent Studio and exposed to a ServiceNow AI Agent through two read-only tools. The end-to-end flow was validated in the deployed environment:

ServiceNow Agent Studio
→ MCP server on Google Cloud Run
→ delegated end-user OAuth
→ ServiceNow resource instance
→ user-scoped tool results

The AI Agent successfully invokes both tools, and ServiceNow scopes the returned records to the signed-in user.

Implemented tools

get_work_items

• Accepts status: open (default) or all.
• Accepts limit: integer from 1 to 100 (default 20).
• Reads incidents where caller_id or opened_by is the signed-in user.
• Reads requested items where requested_for or opened_by is the signed-in user.
• Adds source_table, relationship_to_user, and, for work opened for another person, the display name in other_person.
• Requires mcp.work_items.read.

get_pending_approvals

• Accepts limit: integer from 1 to 100 (default 20).
• Returns only approvals whose state is requested and whose approver is the signed-in user.
• Requires mcp.approvals.read.

Tool inputs cannot select an ownership mode, table, field, encoded query, approver, user identifier, or Dynamic Me filter ID. Responses contain only allowlisted ServiceNow fields and server-derived relationship metadata. See the architecture for the fixed query plans and trust boundaries.

Security highlights

• Authorization Code with canonical PKCE S256.
• Exact OAuth client, redirect URI, scope, and resource binding.
• Delegated ServiceNow execution as the signed-in user.
• Cloud KMS encryption with session- and purpose-bound contexts.
• Opaque MCP refresh tokens stored only as SHA-256 hashes.
• Atomic refresh-token rotation with replay-family session revocation.
• Fixed tables, fields, limits, sorts, and Dynamic Me query plans.
• No arbitrary encoded queries or user identifiers from the AI Agent.
• HTTPS-only ServiceNow token exchange with redirects disabled.
• No access tokens, refresh tokens, authorization codes, record content, or query results in logs.

OAuth flow

The MCP-facing flow supports Authorization Code with PKCE S256 and rotating refresh tokens for public clients:

1. The client calls /oauth/authorize with the canonical MCP resource and an explicit request for one or both supported tool scopes.
2. The runtime validates the OAuth client, exact redirect URI, resource, scopes, and canonical PKCE challenge, then redirects the browser to ServiceNow.
3. The callback exchanges the ServiceNow code and stores both delegated tokens encrypted in the MCP session.
4. The client exchanges the returned MCP authorization code, the same resource, and the PKCE verifier at /oauth/token for an MCP bearer lasting up to 15 minutes and a rotating refresh token.
5. Each tool call validates the MCP bearer, session, and required tool scope before using the delegated ServiceNow bearer for a fixed query.
6. The client renews access with grant_type=refresh_token, the same client_id, and the same resource. Each successful use rotates the MCP refresh token; the delegated ServiceNow token is refreshed only when needed.

Plaintext delegated tokens and plaintext MCP refresh tokens are never stored. Refresh-token reuse revokes the session. MCP refresh tokens expire after 30 days of inactivity, and each token family has a maximum lifetime of 90 days. Users authorize again only after expiry, revocation, or an invalid downstream refresh grant.

Configuration

Required environment variables:

Variable	Purpose
SNOW_QA_URL	HTTPS base URL of the ServiceNow resource instance.
SNOW_QA_DELEGATED_CLIENT_ID	Client ID of the delegated ServiceNow OAuth application.
SNOW_QA_DELEGATED_CLIENT_SECRET	Client secret of the delegated ServiceNow OAuth application.
SNOW_QA_DYNAMIC_ME_FILTER_ID	Sys ID that represent a Dynamic 'Me' Filter.
MCP_TOKEN_KMS_KEY	Full Cloud KMS key resource name used to encrypt delegated tokens.
MCP_TOKEN_SIGNING_SECRET	Base64-encoded MCP signing secret that decodes to at least 32 bytes.

Optional environment variables:

Variable	Default	Purpose
MCP_PUBLIC_URL	http://localhost:8080	Public origin used for OAuth and MCP endpoint metadata.
SNOW_QA_DELEGATED_SCOPE	unset	Scope sent to the delegated ServiceNow authorization endpoint.
PORT	8080	HTTP listener port.

The process also needs Google Application Default Credentials with access to the configured KMS key and Firestore database. OAuth clients are stored in oauth_clients; each active registration must allow only the tool scopes it needs.

Local development

Node.js 20 or later is required. After setting the environment and Google credentials:

npm ci
npm run dev

To run the compiled server:

npm run build
npm start

Validation

The automated tests use mocks and do not require live ServiceNow or GCP credentials:

npm run gcp-build

This command runs the TypeScript typecheck, all 79 automated tests, and the production build. For deployment changes, follow the GCP migration checklist.