Service Mapping MCP tools
The Service Mapping tools, delivered as part of the CMDB MCP Server, expose live application service data and enable AI clients such as Claude to query service topology, identify mapping gaps, and create new application services in natural language.
The Service Mapping MCP tools provide query and create processes for investigating, visualizing, and building 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 CMDB MCP Server, then users can connect Claude Desktop, and use it to query in natural language and create services. Claude selects the appropriate tool, retrieves live data or creates records directly from the ServiceNow® instance over OAuth 2.0 and JWT authentication, and presents the results in several visualizations or confirmations.
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.
- Service creation at scale
- The Create Top Down Service tool enables bulk onboarding of applications without manual efforts. An admin can prompt "create 50 services from this list" and the tool creates application service records, detects entry point types (HTTP vs TCP), and triggers discovery.
- 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 six 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:
- Six scripted REST API tools
- Five tools map to read-only scripted REST API endpoints under /api/sn_sm_gen_ai/ on the ServiceNow instance. One tool, Create Top Down Service, maps to a write-enabled endpoint that creates [cmdb_ci_service_discovered] records and triggers asynchronous Service Mapping discovery. All 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, and ensuring that write operations (service creation) are performed under the authenticated user's permissions. The data sources are CMDB Services tables, CMDB relationships, TCP Traffic, and service record creation tables.
- Asynchronous discovery on write
- When Create Top Down Service creates a new service record, Service Mapping discovery job is initiated from the provided entry point. Discovery runs asynchronously in the background and does not block the tool response. The tool returns immediately to the AI client with the new service system ID, allowing Claude to continue with topology queries or other operations without waiting for discovery to complete.
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 CMDB MCP Server provides six tools: five read-only query tools and one write tool for service creation. All tools are consumable by Claude via the MCP protocol without additional transformation.
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 role requirements, see Configure roles for the Service Mapping MCP tools.
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 - createTopDownService
-
Creates a new application service from a single entry point (HTTP URL or TCP host and port). Automatically detects entry point type, validates inputs, and triggers Service Mapping discovery asynchronously. Use this tool to onboard applications in bulk, stand up services on demand, or automate service creation workflows. For detailed information, see Service Mapping MCP tools reference.
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.