mcp-server-installation

Happy Platform MCP v5.1 のインストール

概要

Happy Platform MCP v5.1 をインストールし、1 つ以上の ServiceNow インスタンスを登録して、認証情報をモデル、MCP メッセージ、ログ、シェル履歴、クライアントの JSON に公開することなく MCP ホストに接続します。MCP を優先する方針を維持してください。ローカルのセットアップ後は、ServiceNow の操作にライブの SN-* ツールを使用してください。raw REST は、操作を実行できる MCP ツールがなく、呼び出し元がローカルで管理された認証情報ヘルパーをすでに利用している場合に限って使用してください。

前提条件

• Node.js >= 20
• Happy Platform MCP 5.1.0 または互換性のあるそれ以降の 5.x リリース
• マスク入力プロンプトを使用できるローカルの対話型ターミナル
• 現在のユーザーが利用できる OS キーチェーン
• MCP 対応クライアントと適切な ServiceNow アクセス権

手順

ステップ 1：サーバーをインストールする

通常のインストールには npm を使用します。

npm install -g [email protected]
happy-platform-mcp --version

代わりに、MCP ホストから npx -y [email protected] を使ってパッケージを起動できます。引数や環境ブロックに認証情報を追加しないでください。

ステップ 2：認証モードを選択する

ローカルで happy-platform-mcp instance add を実行します。必要な値はマスク入力プロンプトを使って対話形式で収集され、認証情報は OS キーチェーンに保存されます。モデルからユーザーに認証情報の貼り付け、エコー、ログ記録、文書化、MCP 呼び出しでの送信を求めてはなりません。

モード	選択する場面	ローカルセットアップの動作
Basic	名前付きの統合ユーザーが必要な場合	ユーザー ID とその認証情報をローカルで求めます
OAuth client_credentials	非対話型のサービス統合が必要な場合	クライアントのメタデータとクライアント認証情報をローカルで求めます
OAuth password	レガシーのリソースオーナーフローが明示的に必要な場合	ユーザーとクライアントの認証情報をローカルで求めます。可能であれば、より強固なフローを優先してください
PKCE を使用する Public authorization_code	ユーザーごとのブラウザーサインインが利用できる場合	静的シークレットを一切使わない直接的な方法です。ブラウザーフローでは更新状態を OS キーチェーンに保存します

ローカル CLI のライフサイクルを使用します。

happy-platform-mcp instance add
happy-platform-mcp instance list
happy-platform-mcp instance test dev
happy-platform-mcp instance update dev
happy-platform-mcp instance remove dev
happy-platform-mcp instance migrate

instance update はメタデータのみを変更します。認証情報を変更するには、削除してから再追加する必要があります。happy-platform-mcp instance credential set dev は、登録済みインスタンスのローテーション、またはメタデータのみで既存の登録を完了する場合に限って使用してください。新しいインスタンス名の初期登録には使用できません。

ステップ 3：レジストリの保存先を確認する

デフォルトのバージョン 1 ユーザーレジストリは ~/.config/happy-platform-mcp/instances.json です。ここに含まれるのは、機密情報を含まないメタデータと正規の credentialRef 値のみです。認証情報は OS キーチェーンに保存されます。レジストリに平文の値を手動で追加しないでください。

HAPPY_CONFIG_PATH はレジストリの場所を上書きし、絶対パス、相対パス、~ を使用できます。CLI の実行前に設定し、MCP ホストにも同じ値を指定してください。これは認証情報ではなくメタデータを指定するため、安全なホスト設定です。

{
  "mcpServers": {
    "happy-platform-mcp": {
      "command": "npx",
      "args": ["-y", "[email protected]"],
      "env": {
        "HAPPY_CONFIG_PATH": "~/.config/happy-platform-mcp/instances.json"
      }
    }
  }
}

パッケージ内の config/servicenow-instances.json は読み取り専用のレガシー移行元であり、書き込み可能な v5.1 レジストリではありません。パッケージ内のレガシー設定からユーザーレジストリへの自動移行では、happy-platform-mcp instance migrate が認証情報を OS キーチェーンに移し、レガシーの移行元は変更しません。上書き先が同じ平文の移行元と移行先を指す場合、移行は書き込み前に拒否されます。別の移行先を選ぶか、instance add で各インスタンスを再作成してください。平文レジストリを手動編集する方法を決して案内しないでください。

ステップ 4：通常モードまたはドキュメント専用モードで起動する

レジストリ／設定もレガシー環境認証情報も存在しない場合、stdio は自動的にドキュメント専用モードにフォールバックします。このモードを明示的に指定するには、次のように設定します。

{
  "env": {
    "HAPPY_MCP_DOCS_ONLY": "true"
  }
}

HAPPY_MCP_DOCS_ONLY=true を使用してください。v5.1 の --docs-only フラグでは、既存のレジストリを確実に上書きできません。ドキュメント専用モードでは、ライブの ServiceNow クライアントを作成せずに、ドキュメントツールと安全な登録ツールを公開します。

ステップ 5：安全な MCP 登録を使用する

SN-Register-Instance はメタデータのみを扱い、シークレットフィールドを拒否します。通常、メタデータを保存し、ライブリロードを実行します。ドキュメントのみのモードで起動したサーバーでは、ServiceNow のライブツールを使用できるようにするため、再起動が必要です。

v5.1 にはブートストラップ上の制約があります。認証情報を使用した登録では、新しいメタデータを書き込む前に認証情報の参照を確認します。一方、instance credential set では、登録済みの名前が必要です。そのため、次のようにしてください。

• Basic、client_credentials、OAuth password には、ローカルの instance add を使用します。
• 静的なクライアント認証情報が不要な公開の authorization_code には、SN-Register-Instance を直接使用できます。
• 外部で事前にプロビジョニングされた決定的なキーチェーン参照がある場合は、認証情報を使用した直接登録も可能です。
• 認証情報やトークンを SN-Register-Instance に渡さないでください。

公開登録の例：

Tool: SN-Register-Instance
Parameters:
  name: public-dev
  url: https://example.service-now.com
  authType: oauth
  grantType: authorization_code
  clientId: registered-public-client-id
  makeDefault: true

ステップ 6：確認してルーティングする

MCP ホストを再起動した後、パラメーターなしで SN-Set-Instance を実行してインスタンスの一覧を表示し、SN-Get-Current-Instance でセッションを確認してから、リスクの低い読み取り操作を実行します。

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

SN-Set-Instance は、連続して実行する作業で使用される、現在のセッションの暗黙的な対象を変更します。同時実行の作業、重要な操作、またはセッション切り替えとの競合が発生する可能性のある操作では、呼び出しごとに明示的な instance 値を渡してください。

ベストプラクティス

• 読み取り専用で開始し、本番環境以外のインスタンスを使用してください。
• インスタンス名は分かりやすくし、書き込み前に現在の対象を確認してください。
• 認証情報は、入力がマスクされるローカルプロンプトと OS キーチェーン内で管理してください。
• 破壊的な操作、本番環境での操作、同時実行の操作、または重要な操作では、明示的なルーティングを使用してください。
• 書き込みを含むワークフローを有効にする前に、happy-platform-mcp instance test <name> を実行してください。
• MCP を優先する方針を維持し、不慣れなテーブルを操作する前に SN-Get-Table-Schema を使用してください。

トラブルシューティング

問題	解決方法
CLI で古い Node ランタイムが報告される	Node 20 以降をインストールし、コマンドを再実行してください
インスタンス名が見つからない	happy-platform-mcp instance list を実行し、ローカルで instance add を使用してください
認証モードを変更する必要がある	instance remove <name> を実行してから、instance add を実行し、新しいモードを選択してください
メタデータは存在するが、認証に失敗する	ローカルで instance credential set <name> を実行してから、instance test <name> を実行してください
ドキュメント用ツールしか表示されない	強制的なドキュメントのみのモードが設定されている場合は解除し、使用可能な登録が存在してから再起動してください
移行でパスが拒否される	レガシーからデフォルトユーザーへの自動移行パスを使用するか、メタデータ専用の別の移行先を選択してください

関連スキル

• admin/instance-management - ランタイムのルーティングと環境の安全性
• development/servicenow-docs-mcp - ドキュメントの検索とドキュメントのみの動作
• development/mcp-server - MCP 互換のカスタム統合を構築する