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.
The output showing 103 named services grouped into categories: Financial, Enterprise platforms, Customer-facing, and Discovered.
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.
The output showing a server connected to four impacted application services via a radial diagram, with the label 4 services impacted if this fails.
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.
Topology graph with 14 members, 21 edges, and 4 CI classes across SERVICE, APP, DB, and HOSTS layers, with Depends on and Runs on edges.
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.
The output showing concentric hop rings with 3 hops, 25 or more CIs reached, 35 edges walked, and a capped traversal depth indicator.
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).
Side-by-side comparison: on the left, get\_server\_impact\_graph showing 35 CMDB-modeled edges and 25 CIs; on the right, get\_unmapped\_topology showing 0 traffic-only edges for the same server, confirming full CMDB coverage.
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.
Setup flow diagram: the admin installs the plugin, configures the role hierarchy, activates the CMDB MCP Server. The user connects Claude Desktop and calls the MCP tools.
- Configure roles for the Service Mapping MCP tools
Configure the role containment chain and assign the required roles to users so they can connect to the CMDB MCP Server and call the Service Mapping MCP tools. - Activate the CMDB MCP Server for Service Mapping tools
Activate the CMDB MCP Server and configure the OAuth inbound integration so that external AI clients can connect to your ServiceNow® instance and query application service data. - Connect Claude Desktop to the Service Mapping MCP Server
Add the Service Mapping MCP Server as a custom connector in Claude Desktop so you can query application service data from your ServiceNow® instance in natural language. - Service Mapping MCP tools reference
Reference information for the six Service Mapping MCP tools provided by the CMDB MCP Server, including their inputs, outputs, and example natural-language queries for use with Claude, and service creation workflows.
Parent Topic:AI capabilities in Service Mapping