instance-management

Instance Management

Overview

Happy Platform MCP v5.1 separates persistent registration from runtime routing. Local CLI commands manage a metadata-only user registry and keychain-backed credentials. MCP tools select a target for the current session or for one explicit call. This separation prevents one workflow from accidentally redirecting another.

Prerequisites

Happy Platform MCP v5.1 configured through development/mcp-server-installation
One or more instances added with the local interactive CLI
Appropriate ServiceNow roles for the intended read or write

Procedure

Step 1: Inspect Registered Instances

For local configuration inspection, prefer:

happy-platform-mcp instance list
happy-platform-mcp instance test dev

From MCP, call parameterless SN-Set-Instance to list the configured choices without changing the target:

Tool: SN-Set-Instance
Parameters: none

There is no separate MCP list tool in v5.1; parameterless SN-Set-Instance is the supported listing operation.

Step 2: Confirm the Session Target

Tool: SN-Get-Current-Instance
Parameters: none

This reports the current session's implicit target. Check it immediately before a sequential write workflow.

Step 3: Select a Target for Sequential Work

Tool: SN-Set-Instance
Parameters:
  instance_name: dev

SN-Set-Instance changes only the current session's implicit target in memory. It does not edit the registry, alter another MCP session, or change the configured startup default. A new session starts from its configured default.

Step 4: Route Concurrent or Critical Calls Explicitly

Every live ServiceNow operation accepts an optional instance parameter except SN-Register-Instance, SN-Set-Instance, SN-Get-Current-Instance, and the documentation tools (SN-Docs-Families, SN-Docs-Status, SN-Docs-Sync, SN-Docs-Search, and SN-Docs-Get). Registration accepts no instance field. An explicit per-call value on supported operations does not mutate the session target.

Tool: SN-Query-Table
Parameters:
  instance: prod
  table_name: incident
  query: active=true^priority=1
  fields: number,short_description,state
  limit: 10

Use explicit instance routing for concurrent work, critical operations, production changes, or calls that could race with SN-Set-Instance. Concurrent calls against one stable implicit target can omit it, but explicit routing is easier to audit.

Step 5: Verify Before a Write

Query an instance-specific property using an explicit target, compare the response with the intended environment, and only then write:

Tool: SN-Query-Table
Parameters:
  instance: dev
  table_name: sys_properties
  query: name=instance_name^ORname=glide.installation.name
  fields: name,value
  limit: 5

Then preserve the same explicit target on the mutation:

Tool: SN-Update-Record
Parameters:
  instance: dev
  table_name: incident
  sys_id: <verified-record-sys-id>
  data:
    work_notes: Verified dev routing before update

Tool Usage

Tool	Purpose
`SN-Set-Instance`	With no parameters, list choices; with `instance_name`, change the sequential session target
`SN-Get-Current-Instance`	Report the current session target
`SN-Query-Table`	Verify or read from an explicit named instance
`SN-Create-Record`	Create on an explicitly verified target
`SN-Update-Record`	Update on an explicitly verified target

Persistent additions, removals, metadata updates, tests, migrations, and credential rotation belong to the local CLI. MCP calls must not collect credential material or modify keychain entries.

Best Practices

Prefer explicit per-call routing for all production writes.
Pair every critical mutation with a same-target read-only verification.
Use SN-Set-Instance only for sequential convenience, never as a parallel isolation mechanism.
Keep development as the configured default when operational policy permits.
Run happy-platform-mcp instance test <name> locally when connectivity changes.
Keep raw REST as a last resort and rely only on a pre-existing local credential helper.

Troubleshooting

Issue	Cause	Resolution
Instance is not listed	It is not in the user registry	Run `happy-platform-mcp instance add` locally
Current target is unexpected	A prior sequential switch changed this session	Call `SN-Get-Current-Instance`, then `SN-Set-Instance` with the intended name
Parallel work reaches the wrong target	Calls relied on mutable session state	Add explicit `instance` to each overlapping call
A new registration is not live	Server started in docs-only mode	Restart the MCP host after registration
Connectivity test fails	Local registration or ServiceNow access is invalid	Run the local `instance test` flow; never send credentials through MCP

Related Skills

development/mcp-server-installation - Secure local registration and migration
admin/generic-crud-operations - Table operations after routing
admin/update-set-management - Environment-specific configuration transport