ServiceNow MCP Server

Secure, enterprise-ready MCP server for ServiceNow where every action runs as the authenticated user.

No shared service accounts. No ACL bypass. Full audit-trail fidelity.

---

⚡ Why This Exists

Instead of funneling every request through a shared service account, this server executes actions as the actual human user.

Because it uses per-user OAuth tokens, ServiceNow still enforces:

• each user's ACLs and roles,
• their approval authority,
• and native user-level audit logging.

Result: safer automation, cleaner compliance, fewer permission hacks.

---

🔥 Core Capabilities

• MCP-spec OAuth 2.0 with PKCE — clients like Claude Code auto-discover and re-auth natively
• Per-user OAuth delegation to ServiceNow (Authorization Code flow + refresh)
• AES-256-GCM encrypted token storage in Redis
• Streamable HTTP MCP transport with per-session lifecycle
• Bearer token auth on every MCP request (Authorization: Bearer)
• Tool-level identity protections for sensitive operations
• Per-user rate limiting via Redis token bucket
• Input validation + normalized error responses
• CI-enforced build + test + coverage gate

---

🚀 Quick Start

npm install
cp .env.example .env
npm run generate-key    # paste into TOKEN_ENCRYPTION_KEY
npm run dev

Health check: curl -s http://localhost:8080/health

For full setup instructions including ServiceNow OAuth configuration, see the Getting Started guide.

---

📚 Documentation

Comprehensive documentation lives in docs/:

• Getting Started — Prerequisites, local dev, OAuth setup, first tool call
• Architecture — System design, session lifecycle, request flow, Redis schema
• Authentication — OAuth flow, token storage, refresh
• Security — Identity enforcement, input validation, rate limiting, error handling
• Tools (35) — All tools: incidents, change requests, knowledge, update sets, and more
• Resources (5) — MCP resources for direct record access
• Prompts (7) — Guided workflows for incidents, change requests, knowledge, and catalog
• HTTP API — Endpoints and client configuration
• Deployment — Docker, Caddy, native TLS, setup script, environment variables
• Development — Adding tools, testing, CI pipeline
• Troubleshooting — Common issues and debug cheat sheet

---

✅ Testing and Quality

npm run build
npm test
npm run test:coverage

• Coverage thresholds are configured in vitest.config.ts
• CI runs build + tests + coverage gate on PRs and main

---

🖥️ Client Config (Claude Desktop / Claude Code)

{
  "mcpServers": {
    "servicenow": {
      "type": "streamablehttp",
      "url": "https://your-host:8080/mcp"
    }
  }
}

MCP clients automatically discover the OAuth endpoints via /.well-known/oauth-authorization-server and handle PKCE-based authentication. No manual link-opening required.

See Client Configuration for deployment-specific examples.

---

💡 Using Prompts and Resources

Once connected, the AI agent has access to tools, resources, and prompts.

Prompts are guided workflow templates the agent uses to walk through multi-step operations. In Claude Code, invoke them with a slash command:

/servicenow:incident_triage
/servicenow:change_request_planning
/servicenow:build_catalog_form

In Claude Desktop, use the prompt picker to browse and select from available prompts.

Resources give the agent read-only access to ServiceNow records by URI. The agent reads these automatically when it needs context — for example, reading servicenow://me for your profile or servicenow://incident/{sys_id} for an incident record.

See Prompts docs and Resources docs for the full list and SDK usage examples.

---

🤖 Agent Instruction Files

• AGENTS.md
• CLAUDE.md
• .github/copilot-instructions.md

Alignment workflow validates expected consistency.

---

Built for secure, user-scoped AI operations in ServiceNow.