servicenow-mcp-ai

Set ServiceNow credentials

servicenow_set_credentials

Idempotent

Save ServiceNow connection credentials to the env file for later REST API requests; set auth method, profile, and host, and pass secrets via elicitation, not arguments.

Instructions

Save connection credentials to the env file for later requests (any subset; auth / oauth_client_id / oauth_grant pick the method). Secrets are never arguments: list them in request_secrets for elicitation. See 'instance' for host changes.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

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

Input Schema

Name	Required	Description
`auth`	No	Stored as SN_AUTH (default: inferred).
`user`	No	ServiceNow username.
`profile`	No	Profile (default active); a new name creates one.
`instance`	No	Instance host, e.g. 'dev12345'. A change needs the new host's auth in the same call (Basic: user + password, else CREDENTIALS_INCOMPLETE) and elicitation confirmation unless SN_ALLOW_UNCONFIRMED_CREDENTIAL_CHANGE=1.
`password`	No	ServiceNow password.
`oauth_grant`	No	Stored as SN_OAUTH_GRANT.
`oauth_client_id`	No	OAuth client id (not a secret).
`request_secrets`	No	Secrets to enter through elicitation (never as arguments).

Schema Changelog

Changes observed during successful MCP inspections.

Changed11 schema fields changedv3.0.0Oct 21, 2026

removedInput schema / $schema

Removed value: -"http://json-schema.org/draft-07/schema#"

addedInput schema / properties / auth

Added value: +{
+  "description": "Stored as SN_AUTH (default: inferred).",
+  "enum": [
+    "basic",
+    "oauth",
+    "apikey",
+    "token",
+    "none"
+  ],
+  "type": "string"
+}

changedInput schema / properties / instance / description

Previous value: -"Instance host, e.g. 'dev12345' or 'dev12345.service-now.com'."New value: +"Instance host, e.g. 'dev12345'. A change needs the new host's auth in the same call (Basic: user + password, else CREDENTIALS_INCOMPLETE) and elicitation confirmation unless SN_ALLOW_UNCONFIRMED_CREDENTIAL_CHANGE=1."

addedInput schema / properties / instance / maxLength
```
Added value: +255
```

addedInput schema / properties / oauth_client_id

Added value: +{
+  "description": "OAuth client id (not a secret).",
+  "maxLength": 1024,
+  "type": "string"
+}

addedInput schema / properties / oauth_grant

Added value: +{
+  "description": "Stored as SN_OAUTH_GRANT.",
+  "enum": [
+    "password",
+    "client_credentials",
+    "refresh_token",
+    "jwt_bearer"
+  ],
+  "type": "string"
+}

addedInput schema / properties / password / maxLength
```
Added value: +1024
```

changedInput schema / properties / profile / description

Previous value: -"Connection profile to write (default: the active one). Use a new name to create a profile."New value: +"Profile (default active); a new name creates one."

addedInput schema / properties / profile / maxLength
```
Added value: +128
```

addedInput schema / properties / request_secrets

Added value: +{
+  "description": "Secrets to enter through elicitation (never as arguments).",
+  "items": {
+    "enum": [
+      "api_key",
+      "oauth_client_secret"
+    ],
+    "type": "string"
+  },
+  "maxItems": 10,
+  "type": "array"
+}

addedInput schema / properties / user / maxLength
```
Added value: +255
```

First observedv2.0.1Sep 5, 2026

TDQS

A4/5.0

Behavior4/5

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

Annotations already declare idempotent, non-destructive, closed-world, so the bar is lower; the description still adds that credentials are persisted to an env file affecting later requests and that secret material flows only through elicitation. The instance-change confirmation rule is echoed from the schema rather than new, which keeps it from a 5.

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

Conciseness4/5

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

Three short sentences, front-loaded with the action and scope before the security constraint. The parenthetical cross-reference ('See instance for host changes') is terse to the point of ambiguity about whether it means the local parameter or a sibling tool.

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 an 8-parameter, no-output-schema config mutation tool, the description covers persistence, partial updates, secret handling, and host-change preconditions. It leaves unclear whether saved credentials overwrite prior ones per profile and whether validation happens before or after the write, but nothing critical to invoking it is absent.

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 the baseline is 3; the description earns above baseline by explaining the cross-parameter logic that the schema cannot express — that zero-required-param calls are valid and that the presence of auth/oauth_client_id/oauth_grant selects the auth method. It does not add much on profile or user semantics.

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: save connection credentials to the env file for later requests, with the partial-update semantics ('any subset') explicit. It distinguishes itself from the record-level CRUD siblings by being configuration-oriented, though it does not name servicenow_use_instance, the closest alternative for instance switching.

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 concrete operational guidance: any subset of params is valid, auth/oauth_client_id/oauth_grant determine the auth method, secrets must be routed through request_secrets rather than passed as arguments, and host changes are governed by the 'instance' field. It stops short of stating when to prefer this over servicenow_use_instance or servicenow_test_connection.

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