{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":843,"path":"api-reference/server-api-reference/MCPClientAPI.md","title":"MCPClient - Scoped","bundle":null,"doc_type":null,"release":"australia","body":"\n# MCPClient- Scoped\n\nThe MCPClient script include is the entry point for interacting with approved Model Context Protocol \\(MCP\\) servers. It provides methods for discovering approved servers, listing and inspecting the tools they expose, and invoking those tools.\n\nThis script include requires the MCP Client plugin \\(sn\\_wdf\\_mcp\\_client\\) and is provided in the `sn_wdf_mcp_client` namespace. The calling user must have the sn\\_mcp\\_client.admin role.\n\nBefore calling this API, complete the required setup:\n\n- [MCP server records](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/intelligent-experiences/working-with-mcp-server-records.md) must be created in the Model Context Protocol Server \\[sn\\_mcp\\_server\\] table, each with a valid connection alias configured for authentication.\n- The AI Governance plugin \\(sn\\_ai\\_governance\\) must be installed. MCP servers must go through the [AI Control Tower \\(AICT\\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/intelligent-experiences/aict-landing.md) approval workflow and reach an `approved` governance status before calling invokeTool\\(\\) on the server.\n\nTypical method call order:\n\n1. getServers\\(\\) — Get the list of approved MCP servers, and obtain each server's sys\\_id.\n2. listTools\\(\\) — For a given server, list the tools that server exposes.\n3. getToolInfo\\(\\) — Optional. For a given server and tool, retrieve that tool's full descriptor \\(its input schema and annotations\\) so calling code knows what arguments to supply.\n4. invokeTool\\(\\) — Call a named tool on a given server with the arguments its input schema requires.\n\nFor more information about tools and MCP schema, see [Model Context Protocol - Tools](https://modelcontextprotocol.io/specification/2025-06-18/server/tools).\n\n**Parent Topic:**[Server API reference](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/api-server.md)\n\n## MCPClient - MCPClient\\(\\)\n\nInstantiates an MCPClient object.\n\n|Name|Type|Description|\n|----|----|-----------|\n|None| ||\n\nThis example instantiates an MCPClient object.\n\n```\nvar client = new sn_wdf_mcp_client.MCPClient();\n```\n\n## MCPClient - getServers\\(Object params\\)\n\nReturns the list of MCP servers the caller is authorized to access. By default, only servers with an AI Governance approval status of `approved` are returned.\n\nMCP Servers are retrieved from the Model Context Protocol Server \\[sn\\_mcp\\_server\\] table.\n\n\n
\n\nName\n\n\n\nType\n\n\n\nDescription\n\n
\n\nparams\n\n\n\nObject\n\n\n\nQuery options.```\n{\n caller_product: \"String\",\n limit: Number,\n offset: Number,\n status: \"String\"\n}\n```\n\n
\n\nparams.caller\\_product\n\n\n\nString\n\n\n\nThe scope name of the application making the API call.\n\n
\n\nparams.limit\n\n\n\nNumber\n\n\n\nOptional. Maximum number of servers to return.Default: 50\n\nMinimum: 1\n\nMaximum: 200\n\n
\n\nparams.offset\n\n\n\nNumber\n\n\n\nOptional. Number of servers to skip before returning results. Used for pagination.Default: 0\n\n
\n\nparams.status\n\n\n\nString\n\n\n\nOptional. Filters results by AI Governance approval status. Valid values:\n\n- `approved`: Returns approved MCP servers.\n- `pending`: Returns MCP servers that are awaiting review or that aren't approved for any reason with an associated error.\n\nDefault: `approved`\n\n
\n
\n\nType\n\n\n\nDescription\n\n
\n\nObject\n\n\n\nResult object containing the list of MCP servers and metadata.```\n{\n \"result\": {\n \"meta\": {Object},\n \"servers\": [Array]\n }\n}\n```\n\n
\n\n<Object>.result.meta\n\n\n\nResult metadata.Data type: Object\n\n```\n\"meta\": {\n \"limit\": \"Number\", \n \"offset\": \"Number\",\n \"total\": \"Number\"\n}\n```\n\n
\n\n<Object>.result.meta.limit\n\n\n\nMaximum number of servers that could be returned in this response.Data type: Number\n\n
\n\n<Object>.result.meta.offset\n\n\n\nNumber of servers skipped before returning results. Used for pagination.Data type: Number\n\n
\n\n<Object>.result.meta.total\n\n\n\nTotal count of matching servers, independent of pagination.Data type: Number\n\n
\n\n<Object>.result.servers\n\n\n\nArray of MCP server objects.Data type: Array\n\n```\n\"servers\": [\n {\n \"governance\": {Object},\n \"name\": \"String\",\n \"server_id\": \"String\",\n \"transport\": \"String\" \n }\n]\n```\n\n
\n\n<Object>.result.servers.governance\n\n\n\nAI Governance approval status.Possible values for **aict\\_status** are `approved` and `pending`.\n\nData type: Object\n\n```\n\"governance\": { \"aict_status\": \"String\" }\n```\n\n
\n\n<Object>.result.servers.name\n\n\n\nName of the MCP server.Data type: String\n\n
\n\n<Object>.result.servers.server\\_id\n\n\n\nSys\\_id of the MCP server.Table: Model Context Protocol Server \\[sn\\_mcp\\_server\\]\n\nData type: String\n\n
\n\n<Object>.result.servers.transport\n\n\n\nCommunication method. The only possible value is `SSE`.Data type: String\n\n
This example fetches the first two approved MCP servers.\n\n```\nvar client = new sn_wdf_mcp_client.MCPClient();\n\nvar result = client.getServers({ limit: 2, offset: 0, caller_product: 'sn_wdf_connect_hub' });\n\ngs.info('Total approved servers: ' + result.meta.total);\nresult.servers.forEach(function(server) {\n gs.info('Server: ' + server.name + ' (' + server.server_id + ')');\n});\n```\n\nOutput:\n\n```\nTotal approved servers: 60\nServer: Atlassian Rovo (08eac8952b3dc7109fadf2a4ce91bf4a)\nServer: Atlassian Rovo (135a815d2be9cf109fadf2a4ce91bf13)\n```\n\n## MCPClient - getToolInfo\\(String serverId, String toolName, Object options\\)\n\nReturns metadata for a single named tool on an approved MCP server.\n\n\n
\n\nName\n\n\n\nType\n\n\n\nDescription\n\n
\n\nserverId\n\n\n\nString\n\n\n\nSys\\_id of the MCP server. This parameter only accepts servers that have an AI Governance approval status of `approved`.Table: Model Context Protocol Server \\[sn\\_mcp\\_server\\]\n\n
\n\ntoolName\n\n\n\nString\n\n\n\nName of the tool. Case sensitive.To view tool names, call [listTools\\(\\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/MCPClientAPI.md).\n\n
\n\noptions\n\n\n\nObject\n\n\n\nOptions object containing the application scope.\n\n
\n\noptions.caller\\_product\n\n\n\nString\n\n\n\nThe scope name of the application making the API call.\n\n
\n
\n\nType\n\n\n\nDescription\n\n
\n\nObject\n\n\n\n```\n// Success result object\n{\n \"status\": \"String\",\n \"tool\": {Object}\n}\n\n// Error result object\n{\n \"status\": \"String\",\n \"errorMessage\": \"String\"\n}\n```\n\n
\n\n<Object>.status\n\n\n\nStatus of the method call.Possible values:\n\n- success\n- error\n\nData type: String\n\n
\n\n<Object>.tool\n\n\n\nTool metadata.Data type: Object\n\n```\n\"tool\": {\n \"annotations\": {Object},\n \"description\": \"String\",\n \"inputSchema\": {Object},\n \"name\": \"String\"\n}\n```\n\n
\n\n<Object>.tool.annotations\n\n\n\nAnnotations.Data type: Object\n\n
\n\n<Object>.tool.description\n\n\n\nDescription of the tool.Data type: String\n\n
\n\n<Object>.tool.inputSchema\n\n\n\nInput schema for the tool.Data type: Object\n\n```\n\"inputSchema\": { \n \"properties\": {Object},\n \"required\": [Array],\n \"type\": \"String\"\n}\n```\n\n
\n\n<Object>.tool.inputSchema.properties\n\n\n\nProperties used in the schema.Data type: Object\n\n
\n\n<Object>.tool.inputSchema.required\n\n\n\nList of properties that are required.Data type: Array\n\n```\n\"required\": [\"String\"]\n```\n\n
\n\n<Object>.tool.inputSchema.type\n\n\n\nSchema type.Data type: String\n\n
\n\n<Object>.tool.name\n\n\n\nName of the tool.Data type: String\n\n
\n\n<Object>.errorMessage\n\n\n\nReturned only on failure. Possible errors: the server is invalid, the tool name is missing, or the tool is not found.Data type: String\n\n
This example retrieves metadata for a single tool.\n\n```\nvar client = new sn_wdf_mcp_client.MCPClient();\nvar serverId = 'a1b2c3d4e5f6a1b2c3d4e5f6';\n\nvar info = client.getToolInfo(serverId, 'addTeamworkGraphContext', {\n caller_product: 'sn_wdf_connect_hub' \n});\n\nif (info.status === 'success') {\n gs.info('Found tool: ' + info.tool.name);\n gs.info('Description: ' + info.tool.description);\n} else {\n gs.warn(info.errorMessage);\n}\n```\n\nOutput:\n\n```\nFound tool: addTeamworkGraphContext\nDescription: Adds a relationship between two entities in the Teamwork Graph (e.g. linking two Jira work items, marking one as blocking another).\n```\n\n## MCPClient - invokeTool\\(String serverId, String toolName, Object toolArguments, Object options\\)\n\nInvokes a named tool on an approved MCP server.\n\n\n
\n\nName\n\n\n\nType\n\n\n\nDescription\n\n
\n\nserverId\n\n\n\nString\n\n\n\nSys\\_id of the MCP server. This parameter only accepts servers that have an AI Governance approval status of `approved`.Table: Model Context Protocol Server \\[sn\\_mcp\\_server\\]\n\n
\n\ntoolName\n\n\n\nString\n\n\n\nName of the tool. Case sensitive.Table:\n\nField: Name\n\n
\n\ntoolArguments\n\n\n\nObject\n\n\n\nOptional. Arguments object passed through to the tool. Shape is tool-specific and defined by the target tool's input schema, for example `{ \"inputs\": { \"toolArguments\": {} } }`.\n\n
\n\noptions\n\n\n\nObject\n\n\n\nOptions object containing the application scope.\n\n
\n\noptions.caller\\_product\n\n\n\nString\n\n\n\nThe scope name of the application making the API call.\n\n
\n
\n\nType\n\n\n\nDescription\n\n
\n\nObject\n\n\n\nResult object containing the payload from invoking the tool.```\n// Success result object\n{\n \"status\": \"String\",\n \"server_id\": \"String\",\n \"tool_name\": \"String\",\n \"result\": {Object}\n}\n\n// Error result object\n{\n \"status\": \"String\",\n \"errorMessage\": \"String\"\n}\n```\n\n
\n\n<Object>.status\n\n\n\nStatus of the method call.Possible values:\n\n- success\n- error\n\nData type: String\n\n
\n\n<Object>.server\\_id\n\n\n\nSys\\_id of the MCP server.Table: Model Context Protocol Server \\[sn\\_mcp\\_server\\]\n\nData type: String\n\n
\n\n<Object>.tool\\_name\n\n\n\nName of the tool.Table:\n\nField: Name\n\nData type: String\n\n
\n\n<Object>.result\n\n\n\nPayload returned after invoking the tool. Shape is tool-specific.Data type: Object\n\n
\n\n<Object>.errorMessage\n\n\n\nReturned only on failure. Error message.Data type: String\n\n
This example invokes the `create_issue` tool on an approved MCP server.\n\n```\nvar client = new sn_wdf_mcp_client.MCPClient();\nvar serverId = 'a1b2c3d4e5f6a1b2c3d4e5f6';\n\nvar response = client.invokeTool(serverId, 'create_issue', {\n \"inputs\": {\n \"toolArguments\": {\n \"issue_title\": \"New issue for MCP\"\n }\n }\n}, {\n caller_product: 'sn_wdf_connect_hub'\n});\n\nif (response.status === 'success') {\n gs.info('Tool ' + response.tool_name + ' invoked on ' + response.server_id);\n gs.info('Result: ' + JSON.stringify(response.result));\n} else {\n gs.error('Invocation failed: ' + response.errorMessage);\n}\n```\n\nOutput:\n\n```\nTool create_issue invoked on a1b2c3d4e5f6a1b2c3d4e5f6\nResult: {\"issue_number\":42,\"url\":\"https://...\"}\n```\n\n## MCPClient - listTools\\(String serverId, String cursor, Object options\\)\n\nLists all tools exposed by a specified approved MCP server.\n\n\n
\n\nName\n\n\n\nType\n\n\n\nDescription\n\n
\n\nserverId\n\n\n\nString\n\n\n\nSys\\_id of the MCP server. This parameter only accepts servers that have an AI Governance approval status of `approved`.Table: Model Context Protocol Server \\[sn\\_mcp\\_server\\]\n\n
\n\ncursor\n\n\n\nString\n\n\n\nOptional. Pagination cursor to start from. Get this value from **next\\_cursor** in the previous result.Default: Starts from the first page.\n\n
\n\noptions\n\n\n\nObject\n\n\n\nOptions object containing the application scope.\n\n
\n\noptions.caller\\_product\n\n\n\nString\n\n\n\nThe scope name of the application making the API call.\n\n
\n
\n\nType\n\n\n\nDescription\n\n
\n\nObject\n\n\n\nResult object containing the list of tools and the next page cursor.```\n// Success result object\n{\n \"result\": {\n \"next_cursor\": \"String,\n \"tools\": [Array]\n }\n}\n\n// Error result object\n{\n \"result\": {\n \"errorMessage\": \"String\", \n \"status\": \"String\" \n }\n}\n```\n\n
\n\n<Object>.result.nextCursor\n\n\n\nPagination cursor to use in the next method call.Data type: String\n\n
\n\n<Object>.result.tools\n\n\n\nArray of tool objects.Data type: Array\n\n```\n\"tools\": [\n {\n \"description\": \"String\",\n \"inputSchema\": {Object},\n \"name\": \"String\"\n }\n]\n```\n\n
\n\n<Object>.result.tools.description\n\n\n\nDescription of the tool.Data type: String\n\n
\n\n<Object>.result.tools.inputSchema\n\n\n\nInput schema for the tool.Data type: Object\n\n```\n\"inputSchema\": { \n \"properties\": {Object},\n \"required\": [Array],\n \"type\": \"String\"\n}\n```\n\n
\n\n<Object>.result.tools.inputSchema.properties\n\n\n\nProperties used in the schema.Data type: Object\n\n
\n\n<Object>.result.tools.inputSchema.required\n\n\n\nList of properties that are required.Data type: Array\n\n```\n\"required\": [\"String\"]\n```\n\n
\n\n<Object>.result.tools.inputSchema.type\n\n\n\nSchema type.Data type: String\n\n
\n\n<Object>.result.tools.name\n\n\n\nName of the tool.Data type: String\n\n
\n\n<Object>.result.errorMessage\n\n\n\nReturned only on failure. Error message.Data type: String\n\n
\n\n<Object>.result.status\n\n\n\nReturned only on failure. The only possible value is `error`.Data type: String\n\n
This example lists the tools exposed by an approved MCP server.\n\n```\nvar client = new sn_wdf_mcp_client.MCPClient(); \nvar serverId = '08eac8952b3dc7109fadf2a4ce91bf4a'; // sys_id of an approved MCP server \n\nvar result = client.listTools(serverId, null, {\n caller_product: 'sn_wdf_connect_hub' \n}); \n\nif (result.status === 'error') { \n gs.error('Could not list tools: ' + result.errorMessage); \n} else { \n gs.info(JSON.stringify(result));\n} \n```\n\nOutput:\n\n```\n{\n \"result\": {\n \"tools\": [\n {\n \"name\": \"addTeamworkGraphContext\",\n \"description\": \"Adds a relationship between two entities in the Teamwork Graph (e.g. linking two Jira work items).\",\n \"inputSchema\": {\n \"type\": \"object\",\n \"properties\": {\n \"cloudId\": {\n \"type\": \"string\",\n \"description\": \"Cloud ID\"\n },\n \"relationshipType\": {\n \"type\": \"string\",\n \"enum\": []\n },\n \"objectIdentifier\": {\n \"type\": \"string\",\n \"maxLength\": 500\n },\n \"targetObjectIdentifier\": {\n \"type\": \"string\",\n \"maxLength\": 500\n }\n },\n \"required\": [\n \"cloudId\",\n \"relationshipType\",\n \"objectIdentifier\",\n \"targetObjectIdentifier\"\n ]\n }\n }\n ],\n \"next_cursor\": null\n }\n}\n```\n\n"}}