Skip to main content
Glama

sn_mcp_register_external_server

Registers an external MCP server with ServiceNow's MCP client so AI agents can use its tools, creating the connection alias, HTTP connection, optional API key credential, and server record.

Instructions

Register an external MCP server (for example the NowAIKit hosted gateway, https://mcp.nowaikit.com/mcp) on the instance's MCP client so ServiceNow AI agents can use its tools. Creates a connection alias, an HTTP connection with the URL, an optional API key credential, and the sn_mcp_server record. Pass connection_alias to reuse an alias you already set up (for OAuth). Adding the server's tools to an agent is then done in AI Agent Studio. REQUIRES WRITE_ENABLED=true and admin.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "name": "<name>"
    },
    "name": "sn_mcp_register_external_server"
  }
}

Input Schema

NameRequiredDescriptionDefault
urlNoStreamable HTTP MCP endpoint (https), e.g. https://mcp.nowaikit.com/mcp
nameYesServer name shown in AI Agent Studio, e.g. "NowAIKit"
api_keyNoOptional API key, stored encrypted in an API Key credential
api_key_headerNoHeader that carries the key (default x-nowaikit-key; use Authorization with api_key_prefix "Bearer" for bearer tokens)
api_key_prefixNoOptional prefix before the key, e.g. Bearer
connection_aliasNoExisting connection alias (sys_alias) sys_id or name to reuse instead of creating one

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv5.0.1

TDQS

A4.1/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already flag a non-read-only, open-world, non-idempotent mutation, and the description goes further by naming the four records created (connection alias, HTTP connection, API key credential, sn_mcp_server) and noting the API key is stored encrypted. It also discloses the admin/WRITE_ENABLED gate. Missing only conflict/re-run behavior for an already-registered server.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the action and resource, then the side effects, then the reuse hint, then prerequisites. Every sentence carries distinct information with no restatement of the name or title.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a six-parameter mutation with no output schema, the description covers side effects, credentials handling, prerequisites, and the follow-on step in AI Agent Studio. It leaves open what is returned (e.g., sys_id) and what occurs if the server name already exists.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so parameter definitions already carry the burden; the description still adds rationale beyond the schema, explaining that connection_alias exists to reuse an existing alias for OAuth flows. It does not elaborate on the api_key_header/prefix interaction beyond what the schema already says.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Register an external MCP server') plus the downstream goal ('so ServiceNow AI agents can use its tools'), and enumerates the artifacts created. The 'external' qualifier implicitly separates it from sn_mcp_create_server, though no sibling is named explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear operational context: pass connection_alias to reuse an existing alias for OAuth, and tool attachment happens afterward in AI Agent Studio. Also states prerequisites (WRITE_ENABLED=true, admin). It stops short of naming when to prefer sn_mcp_unregister_external_server or sn_mcp_activate_server, but the workflow positioning is unambiguous.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools