SavantoAI

@savantoai/mcp-server

Model Context Protocol に対応したローカルサーバーです。Savanto AI ワークスペースを Claude、ChatGPT、Cursor、その他の MCP 互換クライアントに公開します。ダッシュボードを操作する代わりに、自分の AI に話しかけて、ストアの AI アシスタントを設定、コンテンツの登録、運用できます。

できること

設定すると、エージェントは Savanto REST API を反映した厳選されたツールを利用できるようになり、設定 → 状況確認 → 改善の一連のサイクルを網羅します。

カテゴリー	主なツール	対象範囲
ワークスペース	list_workspaces、create_workspace、update_workspace、delete_workspace	tenant:admin
設定	get_workspace_settings、update_workspace_settings、カスタムドメインの CRUD、discover_tools、generate_domain_config、validate_custom_domain、test_domain_connection、generate_color_scheme、チャット／検索ウィジェットの設定	config:admin
コンテンツ	upsert_product／upsert_post（および bulk_*、list_*、get_*、patch_*、delete_*）	admin:products、admin:posts
分類	upsert_taxonomy、bulk_upsert_taxonomies、list/get/delete_taxonomy	admin:taxonomies
プロンプト	upsert_prompt、list_prompts、search_prompts、delete_prompt（および一括操作）	admin:prompts、prompts:read
Webhook	create_webhook、list/get/update/delete_webhook、test_webhook、get_webhook_stats	admin:webhooks
クロール	start_crawl、get_crawl_status／history／config、update_crawl_config	admin:posts
検索	search_products、search_posts	search:products、search:posts
アナリティクス	get_search_analytics、get_chat_analytics、get_feedback_analytics、search_search_logs、list_feedback	tenant:admin、feedback:admin
スレッド	search_threads、get_thread、get_thread_messages、get_thread_analytics、delete_thread、bulk_delete_threads	threads:admin
チャット	chat	chat
診断	whoami、get_tenant_usage	（なし）／tenant:admin

クライアントに安全で分かりやすいツールを提供するため、次の 2 つの仕組みを備えています。

• 起動時にスコープを確認 — サーバーは /tenant/whoami をチェックし、API キーで実際に利用できるツールのみを登録します。エージェントに 403 エラーとなるツールが表示されることはなく、公開可能なウィジェットキーで利用できるツールもごくわずかです。
• 注釈付き — すべてのツールに MCP ヒント（readOnlyHint、destructiveHint、idempotentHint）が付いているため、クライアントは安全な読み取りを自動承認し、破壊的な書き込みに注意を促せます。削除にはさらに、明示的な confirm: true が必要です。

また、一般的な複数ツールのワークフローを手順ごとに説明するプレイブックとして、スキル（MCP プロンプト）も公開します。

• onboard-store-end-to-end – ワークスペースの作成、コンテンツの取り込み、動作とブランド設定、スモークテスト
• onboard-wordpress／onboard-shopify – 各プラットフォームに特化したオンボーディングガイド
• configure-chat – ペルソナ、特別な指示、引き継ぎルールの調整
• configure-custom-domain – カスタム機能（注文追跡、アカウント検索）を MCP サーバー／REST API に接続
• audit-and-improve – 状況確認から改善までのサイクル。失敗したチャット、検索結果ゼロの検索、否定的なフィードバックを見つけて修正
• debug-empty-search – 商品検索で結果が見つからない理由を診断
• migrate-from-competitor – 他社チャットベンダーのエクスポートデータを一括インポート

要件

• Node.js 20 以降
• Savanto のシークレット API キー（if_sk_… で始まるもの）。ダッシュボードの API キーページ で作成できます。

  公開可能キー（if_pk_…）はクライアント側用であり、ワークスペースの作成には使用できません。このキーを指定すると、サーバーは起動を拒否します。

クイックスタート

グローバルインストールは不要です。npx で実行してください。

export SAVANTO_API_KEY=if_sk_your_key_here
npx -y @savantoai/mcp-server

本番環境以外のクラウド（ステージング、ローカル開発環境）を指定する場合：

export SAVANTO_API_URL=http://localhost:3001

リモートサーバー（プレビュー）

上記のローカル stdio サーバーに加えて、同じツール群をホスト型 HTTP サーバーとして実行できるため、クライアントは npx を起動する代わりに URL に接続できます。ローカルに Node を用意したり、マシンごとに設定したりする必要はありません。これはワンクリックの「Claude／ChatGPT に接続」（OAuth）によるオンボーディングに向けた方法です。現時点では、Bearer トークンとしてシークレットキーを受け付けます。

# Each client authenticates per-request — there is NO server-wide key.
SAVANTO_API_URL=https://api.savanto.ai PORT=8080 npx -y -p @savantoai/mcp-server savanto-mcp-http

サーバーは MCP エンドポイントを /mcp に、稼働確認用エンドポイントを /healthz にマウントします。クライアントはキーを Authorization: Bearer if_sk_… として送信します。ツール群は、そのキーのテナントにスコープ制限されており、stdio サーバーとまったく同じです。リモート（Streamable HTTP）サーバーに対応した MCP クライアントから、Bearer トークンを指定して https://your-host/mcp に接続してください。

現在、認証にはシークレットキーをそのまま使用しています。今後のリリースでは、顧客がキーを一切扱わずに接続できるよう、OAuth で発行されたテナントスコープ付きトークンに置き換える予定です。この変更によってトランスポート層とツール層は変わりません。

クライアントの設定

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json（macOS）または %APPDATA%\Claude\claude_desktop_config.json（Windows）を編集します。

{
  "mcpServers": {
    "savanto": {
      "command": "npx",
      "args": ["-y", "@savantoai/mcp-server"],
      "env": {
        "SAVANTO_API_KEY": "if_sk_your_key_here"
      }
    }
  }
}

Claude Desktop を再起動します。メッセージバーにハンマー／ツールのアイコンが表示され、そこに Savanto のツールが一覧表示されます。

Cursor

Cursor の設定 → 機能 → Model Context Protocol → 新しい MCP サーバーを追加：

{
  "savanto": {
    "command": "npx",
    "args": ["-y", "@savantoai/mcp-server"],
    "env": { "SAVANTO_API_KEY": "if_sk_your_key_here" }
  }
}

Cline／Roo／その他の VS Code エージェント

拡張機能の MCP 設定に追加します（通常は ~/.cline などにある JSON ファイルです）。

{
  "mcpServers": {
    "savanto": {
      "command": "npx",
      "args": ["-y", "@savantoai/mcp-server"],
      "env": { "SAVANTO_API_KEY": "if_sk_your_key_here" }
    }
  }
}

OpenAI Agents／Responses API

from openai import OpenAI
from mcp import StdioServerParameters

server = StdioServerParameters(
    command="npx",
    args=["-y", "@savantoai/mcp-server"],
    env={"SAVANTO_API_KEY": "if_sk_your_key_here"},
)

ローカル MCP Inspector（デバッグ用）

npx @modelcontextprotocol/inspector npx @savantoai/mcp-server

Inspector では、ツールの一覧表示や直接実行、リクエスト／レスポンスのペイロードの監視を行える Web UI を利用できます。エージェントにサーバーを渡す前に、キーが正しく設定されているか確認するのに便利です。

プロンプトの例

MCP クライアントにサーバーを登録したら、次を試してみてください。

「acme-store 用に新しい Savanto ワークスペースをセットアップし、https://acme.test をクロールして、アウトドアアドベンチャー風のトーンにし、ウィジェットを #0a7d2c を基調にブランド設定してください。」（オンボーディングを最初から最後まで実行）

「acme-store の過去 30 日間の状況を確認してください。訪問者が検索しても何も見つからなかった内容と、未解決のままの会話は何ですか？ その後、上位のいくつかを解決するコンテンツを追加してください。」（観察→改善のサイクル）

「https://mcp.acme.test/orders の MCP サーバーをバックエンドとして、acme-store に注文追跡機能を追加し、有効化する前に検証とテストを行ってください。」（カスタムドメイン）

「この会話が低評価になったのはなぜですか？」— list_feedback を取得し、スレッドを読み、改善策を提案してください。

エージェントは適切なツールを自動的に選択します（クライアントは読み取り専用のツールを自動承認することもできます）。Skill を明示的に呼び出すこともできます。たとえば Claude Desktop で /onboard-store-end-to-end または /audit-and-improve を実行すると、手順全体が開始されます。

環境変数

変数	デフォルト	用途
SAVANTO_API_KEY	(必須)	シークレット API キー（if_sk_…）。
SAVANTO_API_URL	https://api.savanto.ai	ステージング／ローカル開発用の上書き設定。

セキュリティ

• エージェント／マシンごとに別々の API キーを使用してください。そうすれば、ほかに影響を与えずにキーを 1 つだけ失効できます。API キーのページでは、各キーの最終使用日時を確認できます。
• キーは環境変数を介して渡され、ログに記録されることはありません。サーバーの起動時には、テナント ID とスコープの一覧を示す 1 行の識別バナーが stderr に出力されます。シークレットは含まれません。
• サーバーは stdio 経由で動作し、ネットワークポートを開きません。指定された Savanto API ホストとのみ通信します。
• delete_workspace では、ツール呼び出しに confirm: true パラメーターを明示的に指定する必要があります。これは、誤った推測による破壊的な操作を防ぐための安全策です。

ローカル開発

リポジトリのルートから実行します。

npm install
npm run build --workspace=@savantoai/mcp-server
SAVANTO_API_KEY=if_sk_… SAVANTO_API_URL=http://localhost:3001 node sdks/mcp/dist/stdio.js

テストを実行します。

npm run test --workspace=@savantoai/mcp-server

License

MIT. See LICENSE.