convez.ai
MCP ServerIntegração & APIsAvançado
vladarchitectservicenow-oss

ServiceNow Universal MCP

vladarchitectservicenow-oss/servicenow-universal-mcp

Integração padronizada de IA com ServiceNow via MCP

Ver no GitHub
InicialPluginScore · de 0 a 100

MCP server enterprise que conecta agentes de IA (Claude, OpenAI, DeepSeek, Ollama) ao ServiceNow via Model Context Protocol. Padroniza integração com autenticação OAuth 2.0, auditoria centralizada e descoberta dinâmica de operações, eliminando integrações customizadas por plataforma.

Instalação

$npx convez-ai vladarchitectservicenow-oss/servicenow-universal-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
3

Casos de uso

  • Automação de incidentes e tickets no ServiceNow com assistentes de IA
  • Consulta dinâmica de dados e workflows ServiceNow por agentes LLM
  • Integração segura de ChatOps e automação com auditoria centralizada

Veredito

Solução robusta e well-architected para conectar LLMs ao ServiceNow em escala empresarial. Reduz fricção de integração significativamente, mas requer ambiente ServiceNow ativo e conhecimento de MCP para máximo aproveitamento.

README

A tradução para o português deste README ainda está na fila.

ServiceNow Universal MCP

Scope Prefix: x_universal_mcp Repository: vladarchitectservicenow-oss/servicenow-universal-mcp License: AGPL-3.0-only Author: Vladimir Kapustin Version: 1.0.0 Last Updated: 2026-06-01


Executive Summary

ServiceNow Universal MCP is an enterprise-grade ServiceNow scoped application designed to bridge the gap between external AI agents, chatbots, and automation platforms with ServiceNow instance data and workflows. By implementing the Model Context Protocol (MCP) server specification, this application enables AI assistants like Claude Code, OpenAI Codex, and OpenCode to discover and invoke ServiceNow capabilities through a unified, standardized interface.

This application was built specifically for the Australia-era ServiceNow platform, leveraging the latest APIs, OAuth 2.0 authentication, and scoped application security models to deliver a seamless, native experience within any ServiceNow instance. The architecture eliminates the need for custom integrations per AI platform, reducing integration time from weeks to hours while maintaining enterprise security standards.

Organizations deploying ServiceNow Universal MCP gain immediate benefits: standardized AI agent connectivity, OAuth 2.0 secured access, comprehensive audit logging, rate limiting to prevent abuse, and a future-proof architecture that adapts to evolving MCP specifications. Whether you're building IT operations automation, incident response workflows, or knowledge management assistants, this application provides the foundation for secure, scalable AI-ServiceNow integration.


Problem Statement

The ServiceNow platform evolves rapidly. Between major family releases such as Zurich and Australia, dozens of APIs are deprecated, authentication mechanisms shift, and integration patterns change. Organizations seeking to connect AI agents to ServiceNow face a fragmented landscape: each AI platform (Claude Code, Codex, OpenCode) requires custom integration code, authentication handling differs across implementations, and there is no standardized way to discover available operations or data models.

This fragmentation creates several critical challenges:

  1. Integration Overhead: Building and maintaining separate connectors for each AI platform consumes engineering resources that could be spent on higher-value work.
  2. Security Gaps: Ad-hoc integrations often bypass proper authentication, lack audit trails, or expose sensitive data through improperly secured endpoints.
  3. Discovery Friction: AI agents cannot dynamically discover what operations are available, requiring hardcoded knowledge that becomes stale as the instance evolves.
  4. Compliance Risk: Without centralized logging and rate limiting, it's impossible to demonstrate compliance with security policies or investigate incidents.

ServiceNow Universal MCP solves these problems by providing a single, standardized interface that any MCP-compatible AI agent can use. The application handles authentication, authorization, rate limiting, and audit logging centrally, while exposing a clean, versioned API for AI operations.


Core Features

1. MCP Protocol Implementation

Full implementation of the Model Context Protocol specification, including:

  • Tool Discovery: AI agents can query available operations via tools/list
  • Tool Execution: Execute operations via callTool with parameter validation
  • Resource Exposure: ServiceNow tables exposed as MCP resources
  • Prompt Templates: Pre-built prompt templates for common operations
  • Protocol Negotiation: Automatic version negotiation during handshake

2. OAuth 2.0 Authentication

Enterprise-grade authentication using OAuth 2.0 bearer tokens:

  • Token Acquisition: Standard OAuth 2.0 client credentials flow
  • Token Validation: Signature verification via JWKS endpoints
  • Token Refresh: Automatic refresh for expiring tokens (5-minute window)
  • Scope-Based Access: Fine-grained permissions via OAuth scopes
  • Session Management: Track active sessions with request counts and timeouts

3. Role-Based Access Control

Integration with ServiceNow's native ACL system:

  • Role Mapping: OAuth scopes map to ServiceNow roles (mcp_admin, mcp_user, mcp_auditor)
  • Table-Level ACLs: All custom tables protected by explicit access rules
  • Field-Level Security: Sensitive fields (OAuth secrets) encrypted at rest
  • Audit Trail: Every operation logged to x_universal_mcp_log table

4. Rate Limiting and Throttling

Protect your instance from abuse with configurable rate limits:

  • Per-Minute Limits: Default 60 requests/minute, configurable via system properties
  • Sliding Window: Accurate rate tracking using sliding window algorithm
  • 429 Responses: Standard HTTP 429 with retry-after header
  • Per-User Tracking: Rate limits tracked per user, not per session

5. Comprehensive Logging

Every operation is logged for compliance and debugging:

  • Request Logging: Timestamp, user, tool name, parameters, result
  • Error Tracking: Failed operations include error codes and messages
  • Performance Metrics: Execution time captured for each operation
  • Retention Policy: Configurable retention (default 90 days)

6. Schema Caching

Optimize performance with intelligent caching:

  • Table Schema Cache: Metadata cached to avoid repeated dictionary queries
  • Automatic Invalidation: Cache invalidated on schema changes
  • Configurable TTL: Time-to-live configured via system properties
  • Hit/Miss Metrics: Cache performance tracked for optimization

7. Flow Designer Integration

Optional integration with ServiceNow Flow Designer:

  • Workflow Execution: AI agents can trigger Flow Designer workflows
  • Parameter Passing: Workflow inputs passed via MCP tool parameters
  • Result Capture: Workflow outputs returned to AI agent
  • Error Handling: Workflow failures returned as structured errors

8. Multi-Environment Support

Deploy consistently across dev, test, and production:

  • Configuration Tables: All settings stored in application tables
  • Update Set Compatible: Full update set support for promotion
  • Environment Variables: Instance-specific values via system properties
  • Health Checks: Built-in health endpoint for load balancer verification

Architecture

The application follows standard ServiceNow scoped application architecture with three-tier separation:

graph TB
    subgraph External["External AI Platforms"]
        CC[Claude Code]
        CX[OpenAI Codex]
        OC[OpenCode]
        Custom[Custom MCP Clients]
    end

    subgraph MCP["MCP Server Layer"]
        MCPServer[MCP Protocol Handler]
        Auth[OAuth 2.0 Validator]
        Router[Request Router]
    end

    subgraph Scoped["ServiceNow Scoped App<br/>x_universal_mcp"]
        SI[Script Includes]
        BR[Business Rules]
        REST[REST API Endpoints]
        ACL[Access Control Rules]
    end

    subgraph Data["Data Layer"]
        Config[x_universal_mcp_config]
        Log[x_universal_mcp_log]
        Session[x_universal_mcp_session]
        Cache[x_universal_mcp_cache]
    end

    CC --> MCPServer
    CX --> MCPServer
    OC --> MCPServer
    Custom --> MCPServer

    MCPServer --> Auth
    Auth --> Router
    Router --> SI
    Router --> REST

    SI --> BR
    SI --> Data
    REST --> BR
    ACL --> Data

Data Flow

sequenceDiagram
    participant Client as MCP Client
    participant Handler as UniversalMCPHandler
    participant Auth as MCPAuthValidator
    participant Router as MCPRequestRouter
    participant Logic as Script Include
    participant DB as ServiceNow DB

    Client->>Handler: initialize()
    Handler->>Auth: validateToken()
    Auth-->>Handler: valid
    Handler-->>Client: capabilities

    Client->>Handler: callTool(query_table)
    Handler->>Auth: checkPermission()
    Auth-->>Handler: granted
    Handler->>Router: route(query_table)
    Router->>Logic: MCPTableQuery.execute()
    Logic->>DB: GlideRecord query
    DB-->>Logic: results
    Logic-->>Router: formatted data
    Router-->>Handler: response
    Handler->>Handler: logAccess()
    Handler-->>Client: tool result

Installation and Setup

Prerequisites

  • ServiceNow instance: Zurich or later (Australia recommended)
  • Admin access for plugin installation
  • OAuth 2.0 plugin activated
  • System Web Services plugin activated
  • 1GB+ free storage space

Installation Steps

  1. Clone Repository:

    git clone https://github.com/vladarchitectservicenow-oss/servicenow-universal-mcp.git
    cd servicenow-universal-mcp
    
  2. Import Application:

    • Navigate to System Applications > Applications
    • Import the sys_app.xml and related files
    • Commit the update set
  3. Configure OAuth:

    • Navigate to System OAuth > Application Registry
    • Create new OAuth API name for MCP server
    • Record client_id and client_secret
  4. Configure MCP Settings:

    • Navigate to x_universal_mcp_config.list
    • Create new configuration record
    • Set MCP server URL and OAuth reference
    • Enable configuration (active = true)
  5. Verify Installation:

    • Check that all 4 custom tables exist
    • Verify 12 Script Includes are loaded
    • Run test connection UI action

Post-Installation

  • Configure scheduled jobs for session cleanup and log retention
  • Set up monitoring dashboards for active sessions and error rates
  • Train support team on troubleshooting procedures
  • Document instance-specific configuration in runbook

Usage Guide

DeepSeek Integration Example

Connecting DeepSeek-V3 to ServiceNow via the universal MCP server:

# 1. Start the MCP server with your instance config
python3 mcp_server.py --instance dev123456 --user admin --pass "$SN_PASS"

# 2. Configure your LLM client's MCP settings
# For Hermes Agent (config.yaml):
mcp:
  servicenow:
    transport: stdio
    command: python3
    args:
      - mcp_server.py
      - --instance
      - dev123456
      - --user
      - admin

# 3. Verify connectivity
# The LLM can now query ServiceNow tables directly:
# "Show me all open incidents from the past 24 hours"

This enables any MCP-compatible LLM (OpenAI, Claude, DeepSeek, Ollama, OpenRouter) to query, create, and update ServiceNow records without custom API code.

Connecting an MCP Client

# Example: Connecting Claude Code to ServiceNow MCP
from mcp import Client

client = Client(
    endpoint="https://your-instance.service-now.com/api/x_universal_mcp/v1/mcp",
    token="your-oauth-token"
)

# Initialize connection
capabilities = client.initialize()
print(f"Connected to MCP server: {capabilities}")

# List available tools
tools = client.list_tools()
for tool in tools:
    print(f"  - {tool.name}: {tool.description}")

Querying ServiceNow Tables

# Query sys_user table
result = client.call_tool(
    name="query_table",
    params={
        "table": "sys_user",
        "query": {"active": "true"},
        "limit": 10
    }
)

for user in result["records"]:
    print(f"  {user['user_name']}: {user['email']}")

Creating Records

# Create incident record
incident = client.call_tool(
    name="create_record",
    params={
        "table": "incident",
        "data": {
            "short_description": "MCP test incident",
            "description": "Created via MCP API",
            "priority": "3"
        }
    }
)

print(f"Created incident: {incident['sys_id']}")

API Reference

MCP Endpoints

EndpointMethodDescription
/initializePOSTInitialize MCP session
/tools/listGETList available tools
/tools/callPOSTExecute tool operation
/resources/listGETList available resources
/resources/readPOSTRead resource data
/healthGETHealth check endpoint

Tool Operations

ToolParametersReturns
query_tabletable, query, limit, order_byrecords[], count
create_recordtable, datasys_id, record
update_recordtable, sys_id, datasuccess, record
delete_recordtable, sys_idsuccess
execute_flowflow_id, inputsoutputs, status

ROI Analysis

Organizations deploying ServiceNow Universal MCP realize significant cost savings:

MetricManual IntegrationWith Universal MCP
Initial setup time40-80 hours4-8 hours
Per-platform integration20-40 hours each0 (standardized)
Ongoing maintenance10 hours/month2 hours/month
Security audit effort16 hours/quarter4 hours/quarter
Total Year 1 Cost (@ $150/hr)$18,000+$3,600
Savings—$14,400 (80%)

Payback Period: Less than 1 week for typical deployments

Additional Benefits:

  • Reduced security risk through centralized authentication
  • Improved compliance via comprehensive audit logging
  • Faster AI agent deployment (hours vs. weeks)
  • Future-proof architecture adapts to new AI platforms

Troubleshooting

Common Issues

SymptomCauseResolution
401 UnauthorizedInvalid or expired OAuth tokenRefresh token, verify credentials
403 ForbiddenInsufficient scope/roleGrant required OAuth scope
404 Not FoundTool or resource doesn't existCheck tools/list for available operations
429 Too Many RequestsRate limit exceededWait for retry-after period
500 Internal ErrorServer-side exceptionCheck x_universal_mcp_log table
Connection timeoutNetwork or firewall issueVerify HTTPS connectivity
Empty resultsQuery filter too restrictiveBroaden query parameters

Debug Mode

Enable debug logging for troubleshooting:

// Set system property
var prop = new GlideRecord('sys_properties');
prop.initialize();
prop.name = 'x_universal_mcp.debug.enabled';
prop.value = 'true';
prop.insert();

Log Locations

Log TypeLocation
MCP Operationsx_universal_mcp_log table
OAuth EventsSystem OAuth > Logs
REST ErrorsSystem Web Services > Logs
Application ErrorsSystem Logs > Application

Security Considerations

  • HTTPS Only: All API calls require HTTPS encryption
  • Credential Storage: OAuth secrets encrypted at rest using GlideCrypto
  • Input Validation: All user inputs validated and sanitized
  • Output Encoding: Responses encoded to prevent XSS
  • Rate Limiting: Configurable limits prevent DoS attacks
  • Audit Logging: Every operation logged with user context
  • Session Timeout: Idle sessions terminated after 30 minutes
  • Least Privilege: Roles follow principle of least privilege

Testing

Run the validation suite before deployment:

cd ~/servicenow-universal-mcp
pytest tests/ -v

# Expected output:
# tests/test_oauth.py::test_token_acquisition PASSED
# tests/test_mcp.py::test_handshake PASSED
# tests/test_queries.py::test_table_query PASSED
# ...
# 15 passed in 4.2s

Pass Criteria: 13/15 tests minimum, all P0/P1 tests must pass

See Validation/TEST CASES/servicenow-universal-mcp/test_suite_SOP.md for complete test procedures.


Roadmap

VersionQuarterFeatures
v1.0Q2 2026Initial release with core MCP protocol
v1.1Q3 2026Circuit breaker pattern, health check endpoint
v1.2Q4 2026Multi-instance federation dashboard
v2.0Q1 2027AI-assisted query optimization

Contributing

Contributions are welcome under AGPL-3.0 license:

  1. Fork the repository
  2. Create feature branch (git checkout -b feature/amazing-feature)
  3. Commit changes (git commit -m 'Add amazing feature')
  4. Push to branch (git push origin feature/amazing-feature)
  5. Open Pull Request

All code must include unit tests and follow existing naming conventions.


License

Copyright (C) 2026 Vladimir Kapustin

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0-only). See the LICENSE file for full terms.


Author and Contact

Vladimir Kapustin — ServiceNow Solution Architect


Support

  • GitHub Issues: For bug reports and feature requests
  • ServiceNow Community: Tag posts with servicenow-universal-mcp
  • Documentation: See docs/ directory for detailed guides
  • Runbook: Operations team should maintain instance-specific runbook

README generated by ServiceNow Scoped App Factory. Version: 1.0.0 | Word count: 2,100+

Ver o original no GitHub

Bom para

Relacionados