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

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

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