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 through AI clients like Claude using natural language queries. These tools implement the Model Context Protocol (MCP) on the ServiceNow AI Platform, providing structured and secure access to service topology and mapping data directly from the ServiceNow instance.
Show less
Administrators set up the MCP Server in the MCP admin console, then users connect AI clients such as Claude Desktop to query and visualize service data with live, up-to-date information.
Key Features
- Live AI Access to Service Mapping Data: Unlike static snapshots, these tools provide AI models with real-time access to current service mapping states, ensuring accurate and timely insights.
- Visibility into Unmapped Topology: The tools identify Configuration Items (CIs) with CMDB relationships or TCP traffic signals not yet mapped into service maps, helping admins prioritize mapping efforts proactively.
- Secure, Role-Based Access Control: Access is governed by existing ServiceNow ACLs and role permissions, with OAuth 2.0 and JWT authentication ensuring secure AI client connections and caller-scoped data retrieval.
- No Additional Scripting Required: The five read-only Service Mapping tools come pre-packaged with the CMDB MCP Server and are immediately available upon activation and AI client connection. They return consistent, structured responses and degrade gracefully when data is incomplete.
- Technical Integration: Tools operate as scripted REST API endpoints under /api/snsmgenai/, integrated with MCP Framework version 1.4.2. They enforce scale limits (max 2,000 edges, 4 relationship levels) and target response times under 5 seconds.
Available Tools and Their Uses
- getallapplicationservicenames: Lists all application service names to browse or locate services.
- getallapplicationservicesforaserver: Identifies all services including a specified server, useful for impact assessment during server issues or maintenance.
- getapplicationservicetopology: Retrieves the full current topology of an application service, including member CIs and their relationships.
- getserverimpactgraph: Shows connections from a server CI based on TCP traffic and CMDB relationships, illustrating cascade impact.
- getunmappedtopology: Reveals CIs with relationships or traffic signals not yet mapped into any service, helping identify mapping gaps.
Setup and Usage
- Role Configuration: Administrators must configure role containment chains and assign roles to users for access to the MCP Server and tools.
- Activate MCP Server: Enable the Now Assist CMDB MCP Server and configure OAuth inbound integration with the specific authorization scope for Service Mapping MCP tools.
- Connect AI Client: Users add the MCP Server as a custom connector in Claude Desktop, allowing natural language queries against live application service data.
Practical Benefits for ServiceNow Customers
These tools significantly reduce time to insight by allowing natural-language exploration of application service topologies and their health. They enhance operational visibility, support proactive service mapping improvements, and maintain security and compliance through strict role-based access. Customers can expect faster, more accurate AI-driven service discovery and impact analysis without needing complex scripting or data exports.
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.