{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":31395,"path":"it-operations-management/service-mapping/service-mapping-mcp-server.md","title":"Service Mapping MCP tools","bundle":null,"doc_type":null,"release":"australia","body":"\n# Service Mapping MCP tools\n\nThe Service Mapping tools expose live application service data and enable AI clients to query service topology, identify mapping gaps, and create application services in natural language.\n\nThe 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.\n\nOnce a license is obtained, the admin can set 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 and retrieves live data or creates records directly from the ServiceNow® instance over OAuth 2.0 and JWT authentication. The results are presented in several visualizations or confirmations.\n\n## Benefits\n\n-   **Reduced time to insight**\n\n    Getting a complete picture of an application service through a natural-language query in Claude.\n\n-   **AI access to live Service Mapping data**\n\n    Without the MCP tools, Claude has no programmatic access to live Service Mapping state. They 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.\n\n-   **Visibility into traffic connections outside the CMDB**\n\n    CIs connected only by observed TCP traffic, with no matching Configuration Management Database \\(CMDB\\) relationship, are invisible to operators until something breaks. The get\\_unmapped\\_topology tool surfaces these CIs so admins can prioritize mapping work proactively.\n\n-   **Service creation at scale**\n\n    The create\\_top\\_down\\_application\\_service tool enables bulk onboarding of applications without manual efforts. An admin can prompt \"create services using these entry points\" and the tool creates application service records, detects entry point types \\(HTTP vs TCP\\), and triggers discovery. For detailed information on prompts and outputs, see [Service Mapping MCP tools reference](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/it-operations-management/service-mapping/sm-mcp-tools.md).\n\n-   **Secure, role-controlled access**\n\n    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.\n\n    All six tools require the sm\\_mcp\\_user role.\n\n-   **No additional scripting required**\n\n    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.\n\n\n## How the Service Mapping MCP tools work\n\nThe Service Mapping MCP tools are built on the following technical stack:\n\n-   **Six scripted REST API tools**\n\n    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.\n\n-   **MCP Framework integration**\n\n    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.\n\n-   **OAuth 2.0 and JWT authentication**\n\n    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.\n\n-   **Caller-scoped data access**\n\n    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.\n\n    Write operations \\(service creation\\) are performed under the authenticated user's permissions. A user with the sm\\_mcp\\_user role can call the create\\_top\\_down\\_application\\_service tool.\n\n    The data sources are CMDB Services tables, CMDB relationships, TCP Traffic, and service record creation tables.\n\n-   **Asynchronous discovery on write**\n\n    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. Claude can continue with topology queries or other operations without waiting for discovery to complete.\n\n\n## Scale limits\n\nThe Service Mapping MCP tools enforce the following scale limits to maintain performance.\n\n-   **Edge maximum**\n\n    2,000 edges per topology response.\n\n-   **Traversal depth maximum**\n\n    4 levels of relationship depth per query.\n\n-   **Response time target**\n\n    Under 5 seconds per tool call. The get\\_all\\_application\\_service\\_names tool targets under 3 seconds, enforced through pagination with a page size capped at 800 entries.\n\n\nFor 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.\n\n## Available tools\n\nThe 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.\n\nAccess 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](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/it-operations-management/service-mapping/sm-mcp-config-role-hierarchy.md).\n\nFor detailed input and output specifications and example queries, see [Service Mapping MCP tools reference](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/it-operations-management/service-mapping/sm-mcp-tools.md).\n\n-   **get\\_all\\_application\\_service\\_names**\n\n    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.\n\n    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.\n\n    \\[Omitted image \"sm-mcp-catalog-portfolio.png\"\\] Alt text: The output showing 103 named services grouped into categories: Financial, Enterprise platforms, Customer-facing, and Discovered.\n\n-   **get\\_all\\_application\\_service\\_for\\_server**\n\n    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.\n\n    The following example shows get\\_all\\_application\\_service\\_for\\_server identifying every named service at risk from a single Windows server.\n\n    \\[Omitted image \"sm-mcp-server-triage-radial.png\"\\] Alt text: The output showing a server connected to four impacted application services via a radial diagram, with the label 4 services impacted if this fails.\n\n-   **get\\_application\\_service\\_topology**\n\n    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.\n\n    \\[Omitted image \"sm-mcp-topology.png\"\\] Alt text: 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.\n\n-   **get\\_server\\_impact\\_graph**\n\n    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.\n\n    \\[Omitted image \"sm-mcp-blast-radius.png\"\\] Alt text: The output showing concentric hop rings with 3 hops, 25 or more CIs reached, 35 edges walked, and a capped traversal depth indicator.\n\n-   **get\\_unmapped\\_topology**\n\n    Starting from a single server or application CI, returns the CIs reachable from it by observed TCP traffic only, without traversing CMDB relationships. Use this tool alongside get\\_server\\_impact\\_graph to see what a CMDB-only map is missing.\n\n    The following example shows get\\_server\\_impact\\_graph and get\\_unmapped\\_topology side by side for the same server, illustrating the difference between CMDB-modeled edges \\(left\\) and traffic-only connections not already captured in the CMDB \\(right\\).\n\n    \\[Omitted image \"sm-mcp-impact-vs-unmapped.png\"\\] Alt text: 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.\n\n-   **create\\_top\\_down\\_service**\n\n    Creates a new application service from one or more entry points \\(HTTP URLs or TCP host-and-port pairs\\). Automatically detects each entry point's type and validates inputs. Use this tool to onboard applications, stand up services on demand, or automate service creation workflows.\n\n    Requires the sm\\_mcp\\_user role. For detailed information, see [Service Mapping MCP tools reference](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/it-operations-management/service-mapping/sm-mcp-tools.md)\n\n\n## Setting up the Service Mapping MCP tools\n\nSetting 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.\n\n\\[Omitted image \"mcp-server-flow-sep26.png\"\\] Alt text: Four-stage setup flow: install the MCP plugin and assign roles, activate the MCP server, configure OAuth, then connect Claude Desktop and call the Service Mapping MCP tools.\n\n-   **[Configure roles for the Service Mapping MCP tools](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/it-operations-management/service-mapping/sm-mcp-config-role-hierarchy.md)**  \nAssign the required roles to users so they can connect to the CMDB MCP Server and call the Service Mapping MCP tools.\n-   **[Activate the CMDB MCP Server for Service Mapping tools](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/it-operations-management/service-mapping/activate-sm-mcp-server.md)**  \nActivate 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.\n-   **[Connect Claude Desktop to the Service Mapping MCP Server](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/it-operations-management/service-mapping/connect-claude-desktop-sm-mcp.md)**  \nAdd 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.\n-   **[Service Mapping MCP tools reference](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/it-operations-management/service-mapping/sm-mcp-tools.md)**  \nDetails on the six Service Mapping MCP tools, including their inputs, outputs, and example natural-language queries for use with Claude, and service creation workflows.\n\n**Parent Topic:**[AI in Service Mapping](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/it-operations-management/service-mapping/ai-workflows-service-mapping.md)\n\n"}}