Custify MCP

🚀 @custify/mcp-server

Model Context Protocol (MCP) を通じて、AI ツールをあなたの Custify カスタマーサクセスデータに接続します。

アカウント、ヘルススコア、利用状況データなどのクエリに加え、ノート・タスクの作成やプレイブックのトリガーまで、Claude、Cursor、VS Code、その他 MCP 対応の AI ツールから直接実行できます。

🚀 クイックスタート

2 分以内でセットアップを完了できます。

1️⃣ API キーを取得する

Custify の設定 > 開発者 > API アクセス に移動し、API キーを作成またはコピーします。

2️⃣ インストール

npx @custify/mcp-server

3️⃣ AI ツールを設定する

ご利用のツールに応じて、後述の設定セクションを参照してください。

4️⃣ 試してみる

AI アシスタントに次のように質問してみましょう：

How many churned accounts do I have?

⚙️ 設定

{
  "mcpServers": {
    "custify": {
      "command": "npx",
      "args": ["-y", "@custify/mcp-server"],
      "env": {
        "CUSTIFY_API_KEY": "your-api-key-here"
      }
    }
  }
}

{
  "servers": {
    "custify": {
      "command": "npx",
      "args": ["-y", "@custify/mcp-server"],
      "env": {
        "CUSTIFY_API_KEY": "your-api-key-here"
      }
    }
  }
}

claude mcp add custify -- npx -y @custify/mcp-server \
  --env CUSTIFY_API_KEY=your-api-key-here

docker run -d \
  -p 3000:3000 \
  -e CUSTIFY_API_KEY=your-api-key-here \
  ghcr.io/custifyofficial/custify-mcp:latest

https://your-server.example.com/mcp

🛠️ 利用可能なツール

📊 アカウントツール

list_accounts は、シンプルなタグフィルタリング用の tag_ids と、高度なフィールド用の Custify フルフィルターシステムをサポートしています。アカウントのタグ名を ID に解決するには list_tags を category: "company" と共に使用します。利用可能なフィールドを確認するには list_attributes を entity_type: "account" と共に使用します。

タグフィルターを filters 経由で手動指定する場合、バックエンドでは次の形式を使用します：

{
  "fieldName": "tags",
  "fieldType": "Tag",
  "filterType": "is_any_of",
  "filterValue": ["<company_tag_id>"]
}

タグでサポートされる filterType の値は is_any_of、is_all_of、is_none_of、is_unknown、any_value です。ID ベースのタグフィルターでは、filterValue は空でないタグ ID の配列である必要があります。

フィルター例：

フィールド型ごとに利用可能なフィルター型：

👤 コンタクトツール

list_contacts は list_accounts のコンタクト版です。シンプルなタグフィルタリングには people タグと共に tag_ids を使用し、高度な Custify フィルターを渡すこともできます。コンタクトタグ名を ID に解決するには list_tags を category: "people" と共に使用します。利用可能なコンタクトフィールドを確認するには list_attributes を entity_type: "contact" と共に使用します。

コンタクトフィルター例：

💚 ヘルススコア・利用状況ツール

🔔 アラート・セグメント

✅ タスクトレード

list_tasks はフラットで扱いやすいパラメータを使用します。フィルターは AND で結合されます。"onboarding follow up" のようなタグ名を ID に解決するには、list_tags を category: "task" と共に呼び出します。担当者名を解決するには list_task_filter_values を呼び出します（名前付きのユーザー ID を返します）。

フィルター例：

利用可能なステータスフィルター値：

update_task_status は永続化されたタスクステータスのみを書き込みます：open、done、not_relevant。まず list_tasks で内部の task_id を特定し、その後新しいステータスで update_task_status を呼び出してください。

利用可能な due ショートカット： past_due、today、this_week、this_month、later。カスタム期間には 両方 の due_after と due_before（ISO 日付）を指定してください。due ショートカットと日付範囲ペアは排他的であり、範囲の片方のみを渡した場合は無視されます。

🎯 目標（Objective）ツール

get_account_objectives は account_id（Custify 内部の company ID）または external_account_id（あなたの company_id）を受け付けます。ページネーション、ソート、および objectiveStatus、importance、risk、dueAt などのフィールドに対する Custify フィルターオブジェクトをサポートします。

⚡ アクションツール

タグアクション は entity_type: "account" または entity_type: "contact"、Custify 内部 entity_ids の配列、および tag_id を受け取ります。タグ名を ID に解決するには、まず list_tags または custify://tags リソースを使用してください。

📚 利用可能なリソース

リソースは、AI エージェントが Custify ワークスペースを理解するために使用できる読み取り専用のコンテキストを提供します：

💡 使用例

接続後に AI アシスタントへ問い合わせできる実践的な例を以下に示します。

📊 アカウントの照会

"チャーンしたアカウントはいくつありますか？" churned フィルター付きの list_accounts を使用して、churned = true のアカウントをカウントします。

"ヘルススコアが 30 未満のアカウントをすべて表示して" list_attributes でヘルススコアのフィールド名を特定し、Number フィルター付きの list_accounts を使用します。

"jane@company.com が管理しているアカウントをすべて探して" CSM フィールドに対する User フィルター付きの list_accounts を使用します。

"今四半期にサインアップしたアカウントは？" signed_up_at に対して filterType: "this_quarter" を指定した Date フィルター付きの list_accounts を使用します。

"renewal risk タグが付いたアカウントを表示して" category: "company" 付きの list_tags でタグ ID を解決し、tag_ids 付きの list_accounts を使用します。

👤 コンタクトの照会

"champion タグが付いたコンタクトを表示して" category: "people" 付きの list_tags でタグ ID を解決し、tag_ids 付きの list_contacts を使用します。

"example.com のメールアドレスを持つコンタクトを探して" email に対する String フィルター付きの list_contacts を使用します。

🔍 アカウントの詳細調査

"Acme Corp の完全なサマリーを出して" search_accounts で Acme を検索し、get_account、get_health_scores、get_contacts、get_usage_data、get_segment_membership を使用して包括的なブリーフィングを構築します。

"Acme Corp はどのセグメントに所属していますか？" search_accounts でアカウント ID を検索し、get_segment_membership を使用します。

"Acme Corp の過去 1 か月のヘルススコアのトレンドを見せて" get_health_scores でスコア ID を取得し、履歴値については get_usage_trends を使用します。

✅ タスクの照会

"今日の自分のタスクは？" assignee_id（あなたのユーザー ID）と due: "today" を指定した list_tasks を使用して、日次のタスクリストを取得します。

"Jane に割り当てられた 'onboarding follow up' タグ付きの期限超過タスクをすべて表示して" category: "task" 付きの list_tags でタグ名を ID に、list_task_filter_values で Jane のユーザー ID を解決し、tag_ids、assignee_id、status: "overdue" を指定した list_tasks を使用します。

"Acme Corp で未完了のものは？" search_accounts でアカウント ID を検索し、account_id と status: "open" を指定した list_tasks を使用します。

"オンボーディングレビューのタスクを完了にして" list_tasks で該当タスク ID を検索し、status: "done" を指定した update_task_status を使用します。タスクを再開するには status: "open"、関連なしとしてマークするには status: "not_relevant" を使用します。

🎯 目標（Objective）の照会

"Acme Corp で未完了の目標は？" search_accounts でアカウント ID を検索し、get_account_objectives を使用します。

⚡ アクションの実行

"Acme Corp のフォローアップタスクを作成して：オンボーディングの進捗を確認、期限は次の金曜" search_accounts で Acme を検索し、タイトル・期限・アカウント ID を指定した create_task を使用します。

"Acme Corp にノートを追加して：API レイテンシの懸念について VP of Engineering と話した" search_accounts を使用し、ノート本文を指定した create_note を使用します。

"Acme Corp の renewal prep プレイブックを実行して" playbooks リソースでプレイブック ID を検索し、search_accounts でアカウントを検索し、run_playbook を使用します。

"Acme Corp に renewal risk タグを付けて" search_accounts でアカウント ID を検索し、list_tags または custify://tags でタグ ID を検索し、add_tag_to_entities を使用します。

🔎 データモデルの確認

"アカウントをフィルタリングできるフィールドは？" list_attributes を使用して、利用可能なすべてのフィールドを名前と型と共に返します。

"どのセグメントがありますか？" custify://segments リソースを読み取ります。

"利用可能なプレイブックは？" custify://playbooks リソースを読み取ります。

"どの集計メトリクスとライフサイクルステージがありますか？" custify://calculated-metrics と custify://lifecycles リソースを読み取ります。

"アカウントとコンタクトに使用できるタグは？" custify://tags リソースを読み取ります。

🔧 環境変数

🐳 Docker

HTTP ベースの MCP クライアント向けに、サーバーを Docker コンテナとして実行します：

docker run -d \
  --name custify-mcp \
  -p 3000:3000 \
  -e CUSTIFY_API_KEY=your-api-key-here \
  ghcr.io/custifyofficial/custify-mcp:latest

MCP エンドポイントは http://localhost:3000/mcp、ヘルスチェックエンドポイントは http://localhost:3000/health で利用可能になります。

🔒 セキュリティ

• データフロー： AI ツールは Custify MCP サーバーと通信し、サーバーが認証済みの API 呼び出しを Custify REST API に対して行います。MCP サーバー自体はデータを保存しません。
• API キーの取り扱い： CUSTIFY_API_KEY は環境変数から読み取られ、ログに記録されたり、キャッシュされたり、MCP レスポンス経由で公開されたりすることはありません。STDIO トランスポート使用時は、キーはローカルプロセス内にとどまります。HTTP トランスポート使用時は、デプロイが TLS の背後にあることを確認してください。
• 権限： MCP サーバーは API キーの権限を継承します。ワークフローに必要な最小限のアクセスレベルにスコープされたキーを使用してください。読み取り専用キーはすべての読み取りツールで機能し、書き込みツールには書き込み権限を持つキーが必要です。
• テレメトリなし： サーバーは分析を収集せず、第三者にデータを送信しません。

🛠️ トラブルシューティング

「Error: CUSTIFY_API_KEY environment variable is required」 MCP クライアントの設定で CUSTIFY_API_KEY 環境変数が設定されていることを確認してください。タイプミスがないか、余分なスペースがないかも確認してください。

Claude Desktop でサーバーが接続しない

1. 設定ファイルのパスがご利用の OS に対して正しいことを確認します。
2. 設定を編集した後に Claude Desktop を再起動したことを確認します。
3. npx がシステムの PATH で利用可能であることを確認します。

認証エラー（401） API キーが無効または期限切れの可能性があります。Custify の設定 > 開発者 > API アクセスから新しいキーを生成してください。

権限エラー（403） そのエンドポイントが API キーアクセスで利用できない可能性があります。Custify アカウントに必要な権限があることを確認してください。

タイムアウトまたは接続エラー HTTP トランスポート使用時は、サーバーが実行中でアクセス可能であることを確認してください。PORT 環境変数がデプロイ設定と一致していることを確認します。STDIO トランスポートの場合は、ローカルプロセス間通信をファイアウォールやプロキシがブロックしていないことを確認してください。

別の Custify クラスタの場合 Custify インスタンスが別のクラスタ（例：EU）にある場合は、CUSTIFY_API_URL をクラスタの API URL に設定してください。

Docker コンテナがすぐに終了する docker logs custify-mcp でコンテナログを確認してください。最も一般的な原因は CUSTIFY_API_KEY 環境変数の欠落です。

🤝 コントリビューション

コントリビューションを歓迎します！始めるには：

git clone https://github.com/CustifyOfficial/custify-mcp.git
cd custify-mcp-server
npm install
npm run dev

1. リポジトリをフォークします
2. フィーチャーブランチを作成します：git checkout -b feature/my-feature
3. 変更を加え、テストを追加します
4. テストスイートを実行します：npm test
5. プルリクエストを送信します

大幅な変更を計画している場合は、まず issue を開いてください。

📄 ライセンス

MIT - 詳細は LICENSE を参照してください。