Service Mapping MCP tools
Summarize
Summary of Service Mapping MCP tools
The Service Mapping MCP tools, part of the Now Assist CMDB MCP Server, enable ServiceNow customers to access live application service data and query service topology using natural language via AI clients like Claude. These tools implement the Model Context Protocol (MCP) to provide secure, structured, and real-time access to your Service Mapping data directly from your ServiceNow instance, enhancing visibility and operational insight without requiring additional scripting.
Show less
Key Features
- Natural-language querying: Users can query application service topology and mapping gaps in natural language through AI clients connected to the MCP Server.
- Live data access: AI clients retrieve current Service Mapping data via OAuth 2.0 and JWT authentication, avoiding stale or inaccurate information that results from static snapshots.
- Visibility into unmapped topology: The tools identify configuration items (CIs) connected via CMDB relationships or TCP traffic but not yet mapped, helping prioritize mapping efforts proactively.
- Secure, role-based access: Access is controlled by existing ServiceNow ACLs and roles, ensuring data is only available to authorized users under their permissions.
- Immediate availability: The tools are part of the CMDB MCP Server scoped application and are usable immediately after activation and AI client connection.
- Robust technical integration: The tools operate via five scripted REST API endpoints, use MCP Framework v1.4.2, and enforce OAuth 2.0 with JWT for secure client authentication.
- Performance controls: Limits on topology edges (max 2,000) and relationship traversal depth (max 4 levels) ensure responsive queries with target response times under 5 seconds.
Available Tools and Their Uses
- getallapplicationservicenames: Lists all application services for browsing or locating specific services.
- getallapplicationservicesforaserver: Identifies all application services containing a specified server, useful for impact analysis during server issues or maintenance.
- getapplicationservicetopology: Retrieves the full, current topology of a specified application service including member CIs and relationships.
- getserverimpactgraph: Returns observed connections from a server using TCP traffic and CMDB relationships, useful for cascading impact analysis.
- getunmappedtopology: Shows CIs with connections not yet mapped to services, aiding in identifying and addressing mapping gaps.
All tools are read-only, enforce user permissions, and provide structured outputs compatible with AI tool-calling.
Setup Process
ServiceNow system administrators must:
- Configure role assignments to enable user access to the MCP tools.
- Activate the Now Assist CMDB MCP Server and configure OAuth inbound integration with the correct authorization scope to allow AI clients to connect securely.
Users then connect AI clients like Claude Desktop by adding the MCP Server as a custom connector, enabling natural-language queries against live Service Mapping data.
Benefits for ServiceNow Customers
- Faster insights: Quickly obtain a comprehensive and up-to-date view of application services via natural-language queries.
- Improved operational visibility: Detect and prioritize unmapped CIs before issues arise.
- Secure and compliant access: Leverages existing ServiceNow security frameworks to protect sensitive data.
- Ease of use and integration: No additional scripting required; tools are ready to use once configured.
The Service Mapping tools, delivered as part of the Now Assist CMDB MCP Server, expose live application service data and enable AI clients such as Claude to query service topology and mapping gaps in natural language.
The Service Mapping MCP tools provide query-based processes for investigating and visualizing service topology, by implementing the Model Context Protocol (MCP) on the ServiceNow AI Platform. The MCP gives AI clients structured, secured, tool-based access to your data in the ServiceNow® instance.
The admin sets up the Now Assist CMDB MCP Server in the MCP admin console, then users can connect Claude Desktop, and use it to query in natural language. Claude selects the appropriate tool, retrieves live data directly from the ServiceNow® instance over OAuth 2.0 and JWT authentication, and presents the results in several visualizations.
Benefits
- Reduced time to insight
- Getting a complete picture of an application service through a natural-language query in Claude.
- AI access to live Service Mapping data
- Without the MCP tools, AI models have no programmatic access to live Service Mapping state and must rely on static snapshots or user-provided context, leading to stale or inaccurate outputs. The MCP tools give Claude access to current data directly from the instance at query time.
- Visibility into unmapped topology
- CIs that have Configuration Management Database (CMDB) relationships or TCP traffic signals but have not yet been pulled into a service map are invisible to operators until something breaks. The MCP tools surface these CIs so admins can prioritize mapping work proactively.
- Secure, role-controlled access
- The MCP tools enforce the same ACLs and role permissions that govern standard ServiceNow REST API calls. Each request is executed under the authenticated user's session using caller-scoped data access (GlideRecordSecure). OAuth 2.0 with JWT tokens is used to authenticate the AI client connection.
- No additional scripting required
- The five Service Mapping tools ship as part of the CMDB MCP Server scoped application. Once the server is activated and the AI client is connected, the tools are available immediately. All tools return structured, consistent responses and degrade gracefully when CMDB data is incomplete, returning partial results with a warning flag rather than a hard failure.
How the Service Mapping MCP tools work
The Service Mapping MCP tools are built on the following technical stack:
- Five scripted REST API tools
- Each tool maps to a scripted REST API endpoint under /api/sn_sm_gen_ai/ on the ServiceNow instance. The tools are registered as REST API type tools in the MCP Server Console.
- MCP Framework integration
- The server uses MCP Framework version 1.4.2 (sn_mcp v1.4.2). The MCP Discovery Layer at /sncapps/mcp-server/mcp/... receives tool invocation requests from external clients and routes them to the scripted REST API.
- OAuth 2.0 and JWT authentication
- External clients authenticate using OAuth 2.0 Authorization Code grant with JWT token format. ACL filtering and role-based scope enforcement are applied at the scripted REST API layer. The OAuth inbound integration must use the service_mapping_mcp_auth_scope authorization scope, limited to the MCP Tools API and CMDB Mcp Api. Using a different scope results in a successful OAuth connection but no tools visible in the AI client.
- Caller-scoped data access
- Business logic is executed by the Service Mapping MCP tools, ensuring data is returned only for CIs and services the authenticated user is permitted to access. The data sources are CMDB Services tables, CMDB relationships, and TCP Traffic.
Scale limits
The Service Mapping MCP tools enforce the following scale limits to maintain performance.
- Edge maximum
- 2,000 edges per topology response.
- Traversal depth maximum
- 4 levels of relationship depth per query.
- Response time target
- Under 5 seconds per tool call.
For application services that approach these limits, request summary data rather than full topology to stay within the bounds. For example, ask for member count and edge count only, rather than the full topology.
Available tools
The Now Assist CMDB MCP Server provides five read-only tools. All tools are read-only and do not create, update, or delete records.
The AI client selects the appropriate tool based on the user's natural-language input and passes the required parameters. All five tools are consumable by Claude via the MCP protocol without additional transformation. The tool schemas include input and output field descriptions suitable for AI tool-calling.
Access to each tool is controlled by the same ACLs that apply to the corresponding ServiceNow REST API. If the authenticated user does not have the required role, the tool returns an authorization error.
For detailed input and output specifications and example queries, see Service Mapping MCP tools reference.
- get_all_application_service_names
-
Returns a catalog of all application service names. Use this tool to browse the service catalog or locate a specific service before querying its topology.
The following example shows get_all_application_service_names returning a categorized portfolio view of all mapped services in an instance, broken down by service type.
Figure 1. get_all_application_service_names output - get_all_application_services_for_a_server
-
Returns all application services that include a specified server as a member CI. Use this tool to assess which services are at risk when a server is degraded or undergoing maintenance.
The following example shows get_all_application_services_for_a_server identifying every named service at risk from a single Windows server.
Figure 2. get_all_application_services_for_a_server output - get_application_service_topology
-
Returns the full topology of a specified application service, including all member CIs and the CMDB relationships (edges) connecting them, with CI class, relationship type, and direction. Reflects the current state of the service map, not a cached version.
Figure 3. get_application_service_topology output - get_server_impact_graph
-
Given a server CI, returns the observed connections using TCP traffic edges and CMDB relationships. Use this tool to walk the graph outward from a host and view how far the cascade goes.
Figure 4. get_server_impact_graph output - get_unmapped_topology
- Returns CIs that have CMDB relationships or TCP traffic signals but are not currently members of any application service, filterable by CI class. Use this tool to identify mapping gaps and prioritize further Service Mapping
work.
The following example shows get_server_impact_graph and get_unmapped_topology side by side, illustrating the difference between CMDB-modeled edges (left) and traffic-only unmapped connections (right).
Figure 5. get_unmapped_topology output
Setting up the Service Mapping MCP tools
Setting up the Service Mapping MCP tools involves sequential tasks performed by a system administrator, followed by a connection step performed by each Service Mapping user.