mcp-server

MCP サーバーとしての ServiceNow

概要

このスキルでは、ServiceNow を Model Context Protocol（MCP）サーバーとして設定し、標準化されたプロトコルを通じて AI エージェントが ServiceNow とやり取りできるようにする方法を説明します。

• MCP アーキテクチャと、ツールプロバイダーとしての ServiceNow の役割を理解する
• ServiceNow の操作を AI エージェントに公開するツールの機能を定義する
• エージェントが安全にアクセスできるよう、認証と認可を設定する
• エージェントが検出して操作できるリソースエンドポイントを構築する
• エージェントが利用できるよう、入力検証と出力形式の設定を実装する
• MCP とのやり取りに関するログ記録、レート制限、監視を設定する
• AI エージェントプラットフォームで MCP ツール定義をテストする

使用するタイミング： MCP 標準を通じて AI エージェント（Claude、ChatGPT、Cursor など）が ServiceNow のデータや操作とやり取りできるようにする場合、AI を活用したワークフロー向けに ServiceNow インテグレーションを構築する場合、またはマルチエージェントオーケストレーション用の標準化された API レイヤーを作成する場合に使用します。

前提条件

• ロール： admin、rest_api_explorer、web_service_admin
• プラグイン： com.glide.rest（REST API）、com.snc.oauth（OAuth 2.0）
• アクセス権： sys_rest_api、sys_script_include、sys_properties、sys_oauth_entity テーブルへの書き込みアクセス権
• 知識： REST API 設計、OAuth 2.0、JSON Schema、MCP 仕様の概念
• 関連スキル： REST API 開発については development/scripted-rest-apis、アクセス制御については security/acl-management

手順

ステップ 1：MCP アーキテクチャを理解する

Model Context Protocol は、AI エージェントがツールを検出して利用するための標準インターフェースを定義します。ServiceNow は MCP サーバーとして機能し、エージェントが呼び出せる機能を公開します。

MCP ARCHITECTURE:

[AI Agent (Client)]
       |
       | MCP Protocol (JSON-RPC 2.0)
       |
[MCP Server (ServiceNow)]
       |
       +-- Tools: Operations the agent can perform
       |     +-- query_records: Search ServiceNow tables
       |     +-- create_record: Create new records
       |     +-- update_record: Modify existing records
       |     +-- run_flow: Trigger Flow Designer flows
       |
       +-- Resources: Data the agent can read
       |     +-- incident://INC0010001: Incident record
       |     +-- kb://KB0010001: Knowledge article
       |     +-- cmdb://ci/server001: Configuration item
       |
       +-- Prompts: Predefined interaction templates
             +-- incident-triage: Guide incident categorization
             +-- change-risk: Assess change request risk

ステップ 2：ツールのスキーマを設計する

ServiceNow の操作を公開する MCP ツールを定義します。

ツール定義形式（MCP 標準）：

{
  "name": "sn_query_records",
  "description": "Query ServiceNow records from any table using encoded query syntax. Returns matching records with specified fields.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "table": {
        "type": "string",
        "description": "ServiceNow table name (e.g., incident, change_request, sys_user)"
      },
      "query": {
        "type": "string",
        "description": "Encoded query string (e.g., priority=1^state=2)"
      },
      "fields": {
        "type": "string",
        "description": "Comma-separated list of fields to return"
      },
      "limit": {
        "type": "integer",
        "description": "Maximum records to return (default 10, max 100)",
        "default": 10
      }
    },
    "required": ["table"]
  }
}

コアツールの定義：

ツール名	用途	必須パラメーター	任意パラメーター
sn_query_records	レコードを検索	table	query, fields, limit, order_by
sn_read_record	単一のレコードを取得	table, sys_id	fields
sn_create_record	レコードを作成	table, data
sn_update_record	レコードを更新	table, sys_id, data
sn_get_schema	テーブルのスキーマを取得	table
sn_run_flow	フローを起動	flow_id, inputs
sn_search_kb	ナレッジベースを検索	query	kb_id, limit
sn_add_comment	作業メモ／コメントを追加	table, sys_id, text	type（work_note/comment）

ステップ 3：スクリプト化された REST API を作成する

MCP ツールの操作を実装する REST API エンドポイントを構築します。

MCP アプローチ：

Tool: SN-Create-Record
Parameters:
  table_name: sys_rest_api
  data:
    name: "MCP Server API"
    api_id: "mcp_server"
    namespace: "x_mcp"
    short_description: "Model Context Protocol server endpoint for AI agent integration"
    active: true
    requires_authentication: true

REST アプローチ：

POST /api/now/table/sys_rest_api
Body: {
  "name": "MCP Server API",
  "api_id": "mcp_server",
  "namespace": "x_mcp",
  "short_description": "Model Context Protocol server endpoint for AI agent integration",
  "active": "true",
  "requires_authentication": "true"
}

ステップ 4：リソースエンドポイントを作成する

各 MCP ツール機能に対応する API リソースを構築します。

MCP アプローチ：

Tool: SN-Create-Record
Parameters:
  table_name: sys_rest_api_resource
  data:
    rest_api: [REST_API_SYS_ID]
    name: "Tools List"
    resource_path: "/tools/list"
    http_method: "GET"
    short_description: "Return list of available MCP tools and their schemas"
    script: |
      (function process(/*RESTAPIRequest*/ request, /*RESTAPIResponse*/ response) {
        var tools = [];
        tools.push({
          name: 'sn_query_records',
          description: 'Query ServiceNow records from any table',
          inputSchema: {
            type: 'object',
            properties: {
              table: { type: 'string', description: 'Table name' },
              query: { type: 'string', description: 'Encoded query' },
              fields: { type: 'string', description: 'Fields to return' },
              limit: { type: 'integer', description: 'Max results', default: 10 }
            },
            required: ['table']
          }
        });
        // Add more tool definitions...
        response.setBody({ tools: tools });
      })(request, response);

ツール実行エンドポイント：

Tool: SN-Create-Record
Parameters:
  table_name: sys_rest_api_resource
  data:
    rest_api: [REST_API_SYS_ID]
    name: "Tools Call"
    resource_path: "/tools/call"
    http_method: "POST"
    short_description: "Execute an MCP tool with provided arguments"
    script: |
      (function process(/*RESTAPIRequest*/ request, /*RESTAPIResponse*/ response) {
        var body = request.body.data;
        var toolName = body.name;
        var args = body.arguments || {};

        var handler = new x_mcp.MCPToolHandler();
        var result = handler.execute(toolName, args);

        response.setBody({
          content: [{
            type: 'text',
            text: JSON.stringify(result)
          }]
        });
      })(request, response);

ステップ 5：ツールハンドラーを実装する

MCP ツールの実行を処理する Script Include を作成します。

MCP アプローチ：

Tool: SN-Create-Record
Parameters:
  table_name: sys_script_include
  data:
    name: "MCPToolHandler"
    api_name: "x_mcp.MCPToolHandler"
    script: |
      var MCPToolHandler = Class.create();
      MCPToolHandler.prototype = {
        initialize: function() {},

        execute: function(toolName, args) {
          switch(toolName) {
            case 'sn_query_records':
              return this._queryRecords(args);
            case 'sn_read_record':
              return this._readRecord(args);
            case 'sn_create_record':
              return this._createRecord(args);
            case 'sn_update_record':
              return this._updateRecord(args);
            case 'sn_get_schema':
              return this._getSchema(args);
            default:
              return { error: 'Unknown tool: ' + toolName };
          }
        },

        _queryRecords: function(args) {
          var gr = new GlideRecord(args.table);
          if (!gr.canRead()) return { error: 'Access denied to table: ' + args.table };
          if (args.query) gr.addEncodedQuery(args.query);
          gr.setLimit(Math.min(args.limit || 10, 100));
          gr.query();
          var results = [];
          var fields = args.fields ? args.fields.split(',') : null;
          while (gr.next()) {
            var record = {};
            if (fields) {
              fields.forEach(function(f) {
                record[f.trim()] = gr.getDisplayValue(f.trim());
              });
            } else {
              record.sys_id = gr.getUniqueValue();
              record.display_value = gr.getDisplayValue();
            }
            results.push(record);
          }
          return { records: results, count: results.length };
        },

        _readRecord: function(args) {
          var gr = new GlideRecord(args.table);
          if (!gr.canRead()) return { error: 'Access denied' };
          if (gr.get(args.sys_id)) {
            var record = {};
            var fields = args.fields ? args.fields.split(',') : null;
            if (fields) {
              fields.forEach(function(f) {
                record[f.trim()] = gr.getDisplayValue(f.trim());
              });
            }
            return { record: record };
          }
          return { error: 'Record not found' };
        },

        type: 'MCPToolHandler'
      };
    access: "public"
    active: true

ステップ 6：認証を設定する

エージェントを安全に認証するため、OAuth 2.0 を設定します。認証情報は、モデルコンテキストの外部にある、承認済みのローカル認証情報マネージャーまたはデプロイ用シークレットストアを通じてプロビジョニングします。エージェントに認証情報を収集させたり、ツール呼び出しに含めさせたり、ドキュメント内に生成させたり、シェル引数やクライアントの JSON に追加させたりしないでください。

MCP アプローチ：

Tool: SN-Query-Table
Parameters:
  table_name: sys_oauth_entity
  query: type=client^active=true
  fields: sys_id,name,client_id,redirect_url,token_lifetime,refresh_token_lifetime
  limit: 10

OAuth アプリケーションを作成する：

Tool: SN-Create-Record
Parameters:
  table_name: sys_oauth_entity
  data:
    name: "MCP Agent OAuth Client"
    type: "client"
    client_id: "mcp_agent_client"
    redirect_url: "https://agent.example.com/callback"
    token_lifetime: 1800
    refresh_token_lifetime: 86400
    active: true
    comments: "OAuth client for MCP-compliant AI agents"

認証フロー：

1. 管理者が ServiceNow にクライアントのメタデータを登録します。
2. 承認済みのローカル認証情報ヘルパーが、選択した OAuth 交換を会話およびモデルコンテキストの外部で実行します。
3. インテグレーションのトランスポートが、生成された認証状態をログに記録せずに受け渡します。
4. ServiceNow がリクエストを検証し、インテグレーションユーザーの ACL コンテキストを適用します。

ステップ 7：アクセス制御を実装する

MCP エンドポイントの ACL とレート制限を設定します。

テーブルレベルのアクセス制御：

Tool: SN-Query-Table
Parameters:
  table_name: sys_security_acl
  query: name=sys_rest_api^operation=execute
  fields: sys_id,name,operation,condition,role
  limit: 10

レート制限の設定：

Tool: SN-Create-Record
Parameters:
  table_name: sys_properties
  data:
    name: "x_mcp.rate_limit.per_minute"
    value: "60"
    description: "Maximum MCP API calls per minute per client"
    type: "integer"

アクセス制御マトリックス：

ツール	必要な最小ロール	テーブル ACL チェック	レート制限
sn_query_records	itil	テーブル読み取り ACL	60/min
sn_read_record	itil	テーブル読み取り ACL	60/min
sn_create_record	itil	テーブル作成 ACL	30/min
sn_update_record	itil	テーブル書き込み ACL	30/min
sn_get_schema	itil	なし	10/min
sn_run_flow	flow_operator	フロー ACL	10/min

ステップ 8：入力検証を実装する

不正使用を防ぎ、データ品質を確保するために検証を追加します。

VALIDATION RULES:

Table Name Validation:
- Must exist in sys_db_object
- Must not be in blocklist (sys_user_password, sys_certificate, etc.)
- Must be accessible to the authenticated user

Query Validation:
- Maximum query length: 2000 characters
- No script injection (block javascript: in queries for non-admin)
- Validate encoded query syntax

Field Validation:
- Fields must exist on the target table
- Sensitive fields filtered (password, token, secret fields)

Limit Validation:
- Maximum 100 records per query
- Default 10 if not specified

Data Validation (create/update):
- Validate field types match expected values
- Enforce mandatory field requirements
- Sanitize string inputs

ステップ 9：ログ記録とモニタリングを設定する

すべての MCP インタラクションのログ記録を設定します。

MCP のアプローチ：

Tool: SN-Create-Record
Parameters:
  table_name: sys_properties
  data:
    name: "x_mcp.logging.enabled"
    value: "true"
    description: "Enable logging for all MCP API interactions"
    type: "boolean"

ログエントリの構造：

MCP INTERACTION LOG:
- Timestamp: [ISO 8601]
- Client ID: [OAuth client]
- Tool: [tool_name]
- Arguments: [sanitized args]
- Response Status: [success/error]
- Response Time: [ms]
- Records Affected: [count]
- User Context: [authenticated user]

ステップ 10：MCP 統合をテストする

エージェントプラットフォームで MCP サーバーを検証します。

ツール一覧のテスト： ローカルランタイムでトランスポート認証がすでに設定されている MCP クライアント経由で接続し、公開されているツール一覧を確認します。

ツール実行のテスト： その MCP クライアント経由で、リスクの低い読み取り専用のスキーマツールまたはクエリツールを呼び出します。許可リスト、ACL の適用、レート制限、サニタイズされたログ記録、レスポンスの形式を確認します。生のトランスポートプローブが不可欠な場合は、組織が承認したローカル認証情報ヘルパーを使用し、すべての認証状態をコマンドラインと生成されたドキュメントの外部に保持します。

ツールの使用方法

ツール	目的	使用する場面
SN-Create-Record	REST API、リソース、スクリプトインクルードを作成する	MCP サーバーコンポーネントの構築
SN-Update-Record	API 設定を変更し、スクリプトを更新する	MCP 実装の反復
SN-Query-Table	既存の API、ACL、OAuth 設定を検索する	検出と検証
SN-Get-Table-Schema	ツールのスキーマ用にテーブルフィールドを検出する	スキーマの生成
SN-Get-Record	特定の API またはスクリプトの詳細を確認する	デバッグと検証

ベストプラクティス

1. MCP 仕様に厳密に従う -- ツールのスキーマが MCP JSON Schema 形式に一致することを確認します
2. サーバー間のエージェント認証には OAuth 2.0 クライアントクレデンシャルを使用する
3. テーブルの許可リストを実装する -- エージェントがアクセスできるテーブルを明示的に定義します
4. 機密テーブルを決して公開しない -- 認証情報、証明書、パスワードのテーブルへのアクセスをブロックします
5. 厳格にレート制限を適用する -- AI エージェントは大量のリクエストを生成する可能性があります
6. すべてのインタラクションを記録する -- セキュリティとデバッグのための監査証跡を維持します
7. 表示値を返す -- エージェントは人が読みやすいデータをより適切に扱えます
8. ページネーションを実装する -- 大規模な結果セットにはカーソルベースのページネーションを使用します
9. API にバージョンを付ける -- 下位互換性を保つため、リソースパスにバージョンを含めます
10. 複数のエージェントプラットフォームでテストする -- Claude、ChatGPT などとの互換性を確認します
11. 大規模な参照コーパスは任意機能にする -- デフォルトではライブ／ソースに基づく検索を使用し、ローカルインデックス、SQLite、埋め込み、ベクトル検索は明示的にオプトインする機能にします

トラブルシューティング

問題	原因	解決策
401 Unauthorized	OAuth トークンの有効期限切れまたは無効	トークンを更新し、クライアントクレデンシャルを確認して、トークンの有効期間を確認します
403 Forbidden	ユーザーにテーブルまたは API の ACL がない	OAuth ユーザーに割り当てられたロールを確認し、テーブル ACL を確認します
ツールが見つからない	クライアントとサーバー間のツール名の不一致	tools/list のレスポンスにあるツール名がクライアントの設定と一致することを確認します
結果が空	クエリ構文が正しくない、または一致するレコードがない	ServiceNow でクエリを直接テストし、エンコードされたクエリ構文を確認します
大規模なクエリでタイムアウトする	クエリが返すレコード数が多すぎる	limit を減らし、より具体的なクエリ条件を追加します
ツールハンドラーでスクリプトエラーが発生する	Script Include での実行時例外	システムログ（syslog）を確認し、ハンドラースクリプトにエラー処理を追加します

例

例 1：読み取り専用の基本的な MCP サーバー

シナリオ： インシデントを読み取り専用で検索するための最小限の MCP サーバーをセットアップします。

公開するツール：

• sn_query_incidents - インシデントを検索します
• sn_read_incident - インシデントの詳細を取得します
• sn_search_kb - ナレッジベースを検索します

例 2：完全な ITSM MCP サーバー

シナリオ： 作成・更新機能を備えた完全な ITSM MCP サーバーです。

公開するツール：

• クエリ：インシデント、変更、問題、CI
• 作成：インシデント、変更リクエスト
• 更新：インシデントの状態、割り当て、優先度
• アクション：作業メモの追加、フローの実行
• ナレッジ：ナレッジベースの記事の検索と取得

例 3：人事向けのスコープ付き MCP サーバー

シナリオ： 人事サービスの提供に特化した、部門スコープの MCP サーバーです。

公開するツール：

• hr_query_cases - 人事ケースを検索します（リクエスト元自身のケースに絞り込みます）
• hr_create_case - 新しい人事ケースを申請します
• hr_search_policies - 人事ポリシーのナレッジベースを検索します
• hr_check_benefits - 福利厚生の加入状況を照会します

アクセス制御：

• hr_case テーブルのみアクセスできます
• ユーザーが参照できるのは自身のケースのみです
• 作成できるケースのカテゴリは特定のものに限られます

関連スキル

• development/scripted-rest-apis - ServiceNow での REST API の構築
• security/acl-management - アクセス制御リストの設定
• admin/application-scope - スコープ付きアプリケーションの開発
• genai/build-agent - MCP ツールを利用する AI エージェントの構築
• genai/skill-kit-custom - Now Assist のカスタムスキル開発
• development/servicenow-docs-mcp - Happy Platform MCP 向けの ServiceNowDocs の検索と、任意でのローカルインデックス作成