---
sourceDocument: Australia API Reference
sourceDocumentLink: https://servicenow-prod.fluidtopics.net/r/api-reference

 Release :

    - australia

ft:locale :

    - en-US

ft:publication_title :

    - Australia API Reference

ft:clusterId :

    - crapiref

bundleId :

    - crapiref

workflow :

    - Creator


---

# MCPClient - Scoped

# MCPClient - Scoped {#ariaid-title1}

Release version: Australia  
Updated August 3, 2026  
![](https://www.servicenow.com/docs/portal-asset/ico-clock) 7 minutes to read  
The 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.

This 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.

Before calling this API, complete the required setup:

* MCP server records must be created in the Model Context Protocol Server \[sn_mcp_server\] table, each with a valid connection alias configured for authentication.
* The AI Governance plugin (sn_ai_governance) must be installed. MCP servers must go through the [AI Control Tower (AICT)](https://www.servicenow.com/docs/access?context=aict-landing&version=australia&pubname=australia-intelligent-experiences&ft:locale=en-US) approval workflow and reach an `approved` governance status before calling invokeTool() on the server.

Typical method call order:

1. getServers() --- Get the list of approved MCP servers, and obtain each server's sys_id.
2. listTools() --- For a given server, list the tools that server exposes.
3. 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.
4. invokeTool() --- Call a named tool on a given server with the arguments its input schema requires.

For more information about tools and MCP schema, see [Model Context Protocol - Tools](https://modelcontextprotocol.io/specification/2025-06-18/server/tools).

## MCPClient - MCPClient() {#ariaid-title2}

Instantiates an MCPClient object.
{#MCPClient-MCPClient__table_m1c_c0n_str__entry__3}

| Name | Type | Description |
|-|-|-|
| None |   |   |
[Table 1. Parameters]

{#MCPClient-MCPClient__table_m1c_c0n_str}  
This example instantiates an MCPClient object.

    var client = new sn_wdf_mcp_client.MCPClient();

## MCPClient - getServers(Object params) {#ariaid-title3}

Returns 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.
MCP Servers are retrieved from the Model Context Protocol Server \[sn_mcp_server\] table.
{#MCPClient-getServers__table_gsv_par_01a__entry__3}

| Name | Type | Description |
|-|-|-|
| params | Object | Optional. Query options. Default: `{}` (default values used for all child properties) { limit: Number, offset: Number, status: "String" } |
| params.limit | Number | Optional. Maximum number of servers to return. Default: 50 Minimum: 1 Maximum: 200 |
| params.offset | Number | Optional. Number of servers to skip before returning results. Used for pagination. Default: 0 |
| params.status | String | Optional. Filters results by AI Governance approval status. Valid values: * `approved`: Returns approved MCP servers. * `pending`: Returns MCP servers that are awaiting review or that aren't approved for any reason with an associated error. Default: `approved` |
[Table 2. Parameters]

{#MCPClient-getServers__table_gsv_par_01a} {#MCPClient-getServers__table_gsv_ret_01a__entry__2}

| Type | Description |
|-|-|
| Object | Result object containing the list of MCP servers and metadata. { "result": { "meta": {Object}, "servers": [Array] } } |
| \<Object\>.result.meta | Result metadata. Data type: Object "meta": { "limit": "Number", "offset": "Number", "total": "Number" } |
| \<Object\>.result.meta.limit | Maximum number of servers that could be returned in this response. Data type: Number |
| \<Object\>.result.meta.offset | Number of servers skipped before returning results. Used for pagination. Data type: Number |
| \<Object\>.result.meta.total | Total count of matching servers, independent of pagination. Data type: Number |
| \<Object\>.result.servers | Array of MCP server objects. Data type: Array "servers": [ { "governance": {Object}, "name": "String", "server_id": "String", "transport": "String" } ] |
| \<Object\>.result.servers.governance | AI Governance approval status. Possible values for aict_status are `approved` and `pending`. Data type: Object "governance": { "aict_status": "String" } |
| \<Object\>.result.servers.name | Name of the MCP server. Data type: String |
| \<Object\>.result.servers.server_id | Sys_id of the MCP server. Table: Model Context Protocol Server \[sn_mcp_server\] Data type: String |
| \<Object\>.result.servers.transport | Communication method. The only possible value is `SSE`. Data type: String |
[Table 3. Returns]

{#MCPClient-getServers__table_gsv_ret_01a}  
This example fetches the first two approved MCP servers.

    var client = new sn_wdf_mcp_client.MCPClient();

    var result = client.getServers({ limit: 2, offset: 0 });

    gs.info('Total approved servers: ' + result.meta.total);
    result.servers.forEach(function(server) {
        gs.info('Server: ' + server.name + ' (' + server.server_id + ')');
    });

Output:

    Total approved servers: 60
    Server: Atlassian Rovo (08eac8952b3dc7109fadf2a4ce91bf4a)
    Server: Atlassian Rovo (135a815d2be9cf109fadf2a4ce91bf13)

## MCPClient - getToolInfo(String serverId, String toolName) {#ariaid-title4}

Returns metadata for a single named tool on an approved MCP server.
{#MCPClient-getToolInfo__table_gti_par_03a__entry__3}

| Name | Type | Description |
|-|-|-|
| serverId | String | Sys_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\] |
| toolName | String | Name of the tool. Case sensitive. To view tool names, call [listTools()](https://servicenow-prod.fluidtopics.net/aj5D4tX3SClA7W~546pNGA#MCPClient-listTools "Lists all tools exposed by a specified approved MCP server."). |
[Table 4. Parameters]

{#MCPClient-getToolInfo__table_gti_par_03a} {#MCPClient-getToolInfo__table_gti_ret_03a__entry__2}

| Type | Description |
|-|-|
| Object | // Success result object { "status": "String", "tool": {Object} } // Error result object { "status": "String", "errorMessage": "String" } |
| \<Object\>.status | Status of the method call. Possible values: * success * error {#MCPClient-getToolInfo__ul_c2m_34d_2kc} Data type: String |
| \<Object\>.tool | Tool metadata. Data type: Object "tool": { "annotations": {Object}, "description": "String", "inputSchema": {Object}, "name": "String" } |
| \<Object\>.tool.annotations | Annotations. Data type: Object |
| \<Object\>.tool.description | Description of the tool. Data type: String |
| \<Object\>.tool.inputSchema | Input schema for the tool. Data type: Object "inputSchema": { "properties": {Object}, "required": [Array], "type": "String" } |
| \<Object\>.tool.inputSchema.properties | Properties used in the schema. Data type: Object |
| \<Object\>.tool.inputSchema.required | List of properties that are required. Data type: Array "required": ["String"] |
| \<Object\>.tool.inputSchema.type | Schema type. Data type: String |
| \<Object\>.tool.name | Name of the tool. Data type: String |
| \<Object\>.errorMessage | Returned only on failure. Possible errors: the server is invalid, the tool name is missing, or the tool is not found. Data type: String |
[Table 5. Returns]

{#MCPClient-getToolInfo__table_gti_ret_03a}  
This example retrieves metadata for a single tool.

    var client = new sn_wdf_mcp_client.MCPClient();
    var serverId = 'a1b2c3d4e5f6a1b2c3d4e5f6';

    var info = client.getToolInfo(serverId, 'addTeamworkGraphContext');

    if (info.status === 'success') {
        gs.info('Found tool: ' + info.tool.name);
        gs.info('Description: ' + info.tool.description);
    } else {
        gs.warn(info.errorMessage);
    }

Output:

    Found tool: addTeamworkGraphContext
    Description: Adds a relationship between two entities in the Teamwork Graph (e.g. linking two Jira work items, marking one as blocking another).

## MCPClient - invokeTool(String serverId, String toolName, Object toolArguments) {#ariaid-title5}

Invokes a named tool on an approved MCP server.
{#MCPClient-invokeTool__table_ivt_par_04a__entry__3}

| Name | Type | Description |
|-|-|-|
| serverId | String | Sys_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\] |
| toolName | String | Name of the tool. Case sensitive. Table: Field: Name |
| toolArguments | Object | Optional. Arguments object passed through to the tool. Shape is tool-specific and defined by the target tool's input schema, for example `{ "inputs": { "toolArguments": {} } }`. |
[Table 6. Parameters]

{#MCPClient-invokeTool__table_ivt_par_04a} {#MCPClient-invokeTool__table_ivt_ret_04a__entry__2}

| Type | Description |
|-|-|
| Object | Result object containing the payload from invoking the tool. // Success result object { "status": "String", "server_id": "String", "tool_name": "String", "result": {Object} } // Error result object { "status": "String", "errorMessage": "String" } |
| \<Object\>.status | Status of the method call. Possible values: * success * error {#MCPClient-invokeTool__ul_c2m_34d_2kc} Data type: String |
| \<Object\>.server_id | Sys_id of the MCP server. Table: Model Context Protocol Server \[sn_mcp_server\] Data type: String |
| \<Object\>.tool_name | Name of the tool. Table: Field: Name Data type: String |
| \<Object\>.result | Payload returned after invoking the tool. Shape is tool-specific. Data type: Object |
| \<Object\>.errorMessage | Returned only on failure. Error message. Data type: String |
[Table 7. Returns]

{#MCPClient-invokeTool__table_ivt_ret_04a}  
This example invokes the `create_issue` tool on an approved MCP server.

    var client = new sn_wdf_mcp_client.MCPClient();
    var serverId = 'a1b2c3d4e5f6a1b2c3d4e5f6';

    var response = client.invokeTool(serverId, 'create_issue', {
        "inputs": {
            "toolArguments": {
                "issue_title": "New issue for MCP"
            }
        }
    });

    if (response.status === 'success') {
        gs.info('Tool ' + response.tool_name + ' invoked on ' + response.server_id);
        gs.info('Result: ' + JSON.stringify(response.result));
    } else {
        gs.error('Invocation failed: ' + response.errorMessage);
    }

Output:

    Tool create_issue invoked on a1b2c3d4e5f6a1b2c3d4e5f6
    Result: {"issue_number":42,"url":"https://..."}

## MCPClient - listTools(String serverId, String cursor) {#ariaid-title6}

Lists all tools exposed by a specified approved MCP server.
{#MCPClient-listTools__table_lst_par_02a__entry__3}

| Name | Type | Description |
|-|-|-|
| serverId | String | Sys_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\] |
| cursor | String | Optional. Pagination cursor to start from. Get this value from next_cursor in the previous result. Default: Starts from the first page. |
[Table 8. Parameters]

{#MCPClient-listTools__table_lst_par_02a} {#MCPClient-listTools__table_lst_ret_02a__entry__2}

| Type | Description |
|-|-|
| Object | Result object containing the list of tools and the next page cursor. // Success result object { "result": { "next_cursor": "String, "tools": [Array] } } // Error result object { "result": { "errorMessage": "String", "status": "String" } } |
| \<Object\>.result.nextCursor | Pagination cursor to use in the next method call. Data type: String |
| \<Object\>.result.tools | Array of tool objects. Data type: Array "tools": [ { "description": "String", "inputSchema": {Object}, "name": "String" } ] |
| \<Object\>.result.tools.description | Description of the tool. Data type: String |
| \<Object\>.result.tools.inputSchema | Input schema for the tool. Data type: Object "inputSchema": { "properties": {Object}, "required": [Array], "type": "String" } |
| \<Object\>.result.tools.inputSchema.properties | Properties used in the schema. Data type: Object |
| \<Object\>.result.tools.inputSchema.required | List of properties that are required. Data type: Array "required": ["String"] |
| \<Object\>.result.tools.inputSchema.type | Schema type. Data type: String |
| \<Object\>.result.tools.name | Name of the tool. Data type: String |
| \<Object\>.result.errorMessage | Returned only on failure. Error message. Data type: String |
| \<Object\>.result.status | Returned only on failure. The only possible value is `error`. Data type: String |
[Table 9. Returns]

{#MCPClient-listTools__table_lst_ret_02a}  
This example lists the tools exposed by an approved MCP server.

    var client = new sn_wdf_mcp_client.MCPClient(); 
    var serverId = '08eac8952b3dc7109fadf2a4ce91bf4a'; // sys_id of an approved MCP server 

    var result = client.listTools(serverId); 

    if (result.status === 'error') { 
       gs.error('Could not list tools: ' + result.errorMessage); 
    } else { 
       gs.info(JSON.stringify(result));
    } 

Output:

    {
      "result": {
        "tools": [
          {
            "name": "addTeamworkGraphContext",
            "description": "Adds a relationship between two entities in the Teamwork Graph (e.g. linking two Jira work items).",
            "inputSchema": {
              "type": "object",
              "properties": {
                "cloudId": {
                  "type": "string",
                  "description": "Cloud ID"
                },
                "relationshipType": {
                  "type": "string",
                  "enum": []
                },
                "objectIdentifier": {
                  "type": "string",
                  "maxLength": 500
                },
                "targetObjectIdentifier": {
                  "type": "string",
                  "maxLength": 500
                }
              },
              "required": [
                "cloudId",
                "relationshipType",
                "objectIdentifier",
                "targetObjectIdentifier"
              ]
            }
          }
        ],
        "next_cursor": null
      }
    }