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: Delegated read flow validated end to end; constrained approval-write path implemented and awaiting disposable sandbox validation Stack: TypeScript · Node.js · MCP · ServiceNow · Cloud Run · Firestore · Cloud KMS Validation: 94 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 reads and approval transition"| 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.

Related MCP server: NowAIKit

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 read tools, and ServiceNow scopes the returned records to the signed-in user. This deployed demo did not validate a live approval write. The write tool is restricted to disposable sandbox/development validation until the Table API write is replaced by a transactional Scripted REST compare-and-update endpoint and the complete write flow is validated live.

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.

• Projects canonical state, source_table, and timestamps from ServiceNow values while returning human-readable reference display values; reference SYS_IDs are not exposed.

• Fails closed when the display_value=all response is malformed or the approver has no usable display value.

• Requires mcp.approvals.read.

approve_pending_approval

• Accepts only an exact approval sys_id, the previously observed update time, an optional sys_mod_count, and an idempotency key.

• The server fixes the table to sysapproval_approver, verifies Dynamic Me ownership and requested state, and permits only the transition to approved.

• Requires the separate mcp.approvals.approve scope; a read credential cannot invoke it.

• Uses a durable Firestore write claim. A known terminal result is replayed, while an ambiguous post-dispatch outcome is never retried automatically.

• ServiceNow Table API does not provide a documented atomic conditional-update primitive here, so the implementation reports its GET/PATCH stale-state check honestly (atomic_compare_and_update: false). Production hardening should use a narrow Scripted REST compare-and-update endpoint.

• This path is implemented and covered by mocked automated tests, but it has not been validated by mutating the deployed demo instance. Keep the write scope off production clients until the production hardening and live-validation gates are complete.

Tool inputs cannot select an ownership mode, table, field, encoded query, approver, user identifier, target state, 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.

• Separate read/write MCP scopes and durable at-most-once approval-write claims.

• 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 more 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 server-owned query or write transition.

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:

Optional environment variables:

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 94 automated tests, and the production build. For deployment changes, follow the GCP migration checklist.