セットアップ

Analyticsの3ツールはNode.js 0.7.0／Python 0.4.0のソースに追加されています。Remote MCPの配備とnpm/PyPI公開は別工程です。接続先の tools/list で提供状況を確認してください。

全 32 ツールを利用するには、Remote MCP（Streamable HTTP） に直接接続してください。ローカル stdio プロキシも利用できますが、公開ツールとパラメーターはパッケージ・バージョンによって異なります。実際の一覧は MCP の tools/list で確認できます。

	ローカルstdioプロキシ	リモートHTTP直接接続
パッケージ/URL	`@duzzle/shanone-mcp`(npm)	`https://mcp.shanone.ai/mcp`
ローカルにNode.jsが必要か	必要(18以上)	不要
必要な認証	APIキーのみ	APIキーと組織ID
向いている用途	stdio が必要なクライアント	現在の全 32 ツールを利用する場合

前提条件

サポート対象クライアントのいずれか: Cursor、Claude Code、またはCodex
Shanoneアカウントと、Settings → API Keysから取得したAPIキー(sh_で始まります)
ローカルプロキシを使う場合はNode.js 18以上

ステップ1: APIキーを取得する

サインインする

app.shanone.aiにアクセスしてサインインします。

API Keysを開く

Settings → API Keysに移動します。

キーを作成する

Create API Keyをクリックし、名前を付けて有効期限を選択します（初期値は30日）。7日・60日・90日・カスタム（1〜366日）・無期限も選べます。作成後に平文の値をコピーしてください——sh_xxxxxxxxxxxxxxxxという形式で、1度だけ表示されます。有効期間や切り替え方法の詳細は有効期限を参照してください。

APIキーはパスワードと同じように扱ってください。バージョン管理にコミットしたり、公開して共有したりしないでください。

ステップ2: クライアントを設定する

HTTP 接続に対応したクライアントでは、以下の URL とヘッダーを設定します。下の Cursor の直接接続例も参照してください。stdio 専用クライアント向けのプロキシ例は別のタブに掲載しています。

URL: https://mcp.shanone.ai/mcp
Authorization: Bearer sh_xxxxxxxxxxxxxxxx
X-Org-Id: org_xxxxxxxxxxxxxxxx

Cursor (local proxy)
Cursor (direct HTTP)
Claude Code (local proxy)
Codex (local proxy)

~/.cursor/mcp.jsonを編集します(またはCursor Settings → MCPからサーバーを追加します)。

{
  "mcpServers": {
    "shanone": {
      "command": "npx",
      "args": ["-y", "@duzzle/shanone-mcp"],
      "env": {
        "SHANONE_API_KEY": "sh_xxxxxxxxxxxxxxxx"
      }
    }
  }
}

MCPサーバーを読み込むため、Cursorを再起動してください。

{
  "mcpServers": {
    "shanone": {
      "url": "https://mcp.shanone.ai/mcp",
      "headers": {
        "Authorization": "Bearer sh_xxxxxxxxxxxxxxxx",
        "X-Org-Id": "org_xxxxxxxxxxxxxxxx"
      }
    }
  }
}

組織IDは、APIキーと同じSettings → API Keysページで確認できます。

claude mcp add shanone \
  --env SHANONE_API_KEY=sh_xxxxxxxxxxxxxxxx \
  -- npx -y @duzzle/shanone-mcp

または、プロジェクト内の.mcp.jsonを編集します。

{
  "mcpServers": {
    "shanone": {
      "command": "npx",
      "args": ["-y", "@duzzle/shanone-mcp"],
      "env": {
        "SHANONE_API_KEY": "sh_xxxxxxxxxxxxxxxx"
      }
    }
  }
}

~/.codex/config.tomlを編集します。

[mcp_servers.shanone]
command = "npx"
args = ["-y", "@duzzle/shanone-mcp"]

[mcp_servers.shanone.env]
SHANONE_API_KEY = "sh_xxxxxxxxxxxxxxxx"

上記のプレースホルダーのキー/組織IDは、すべて実際の値に置き換えてください。

プランと接続先の確認

Remote Skills は Plus / Pro / Team / Enterprise で利用できます。Free でもツールは表示されますが、実行時は PLAN_UPGRADE_REQUIRED になります。
shanone_health_check は Shanone への接続確認です。Gmail など外部サービスの認証確認には shanone_check_connection を使います。
Gmail の実行には shanone_list_connections で取得した connection_id が必要です。CONNECTION_SELECTION_REQUIRED が返ったら ID を指定してください。
shanone_create_execution_context、shanone_get_execution_context、shanone_switch_connection は削除されました。クライアントのツール一覧を更新してください。
更新後の実装は shanone_execute_tool.arguments をオブジェクトとして受け付けます。引数なしは {} です。再接続して tools/list を更新し、対応バージョンと反映状況も確認してください。

Pythonプロキシ(代替手段)

Python中心の環境向けに、Pythonパッケージも用意されています。

pip install shanone-mcp

{
  "mcpServers": {
    "shanone": {
      "command": "shanone-mcp",
      "env": {
        "SHANONE_API_KEY": "sh_xxxxxxxxxxxxxxxx"
      }
    }
  }
}

接続を確認する

クライアントのAIチャットを開く

MCPに接続されたチャットインターフェースであれば何でも構いません。

ヘルスチェックを依頼する

「Shanoneの接続状態を確認して」と伝えます。

結果を確認する

shanone_health_checkが、APIキーが有効でデータベースに到達可能な、健全なステータスを報告するはずです。

設定リファレンス

設定項目	値
ローカルプロキシパッケージ	`@duzzle/shanone-mcp`(npm)、環境変数`SHANONE_API_KEY`が必要、Node.js 18以上
リモート直接接続URL	`https://mcp.shanone.ai/mcp`(Streamable HTTP)
認証ヘッダー(両方式共通)	`Authorization: Bearer <api_key>`(`X-API-Key`も可)
追加ヘッダー(直接接続のみ)	`X-Org-Id: <org_id>`(または`?org_id=`クエリパラメータでも可)

トラブルシューティング

401 api_key_required

APIキーが送信されていません。設定のenv/headersブロックが、上記の内容と正確に一致しているか確認してください。

401 invalid_api_key

キーが欠落している、不正な形式である、無効化されている、または期限切れです。Settings → API Keysで状態と有効期限を確認してください。期限切れ・無効化済みの場合は、新しいキーを作成してクライアント設定を更新します。古いキーの再有効化はできません。有効期限も参照してください。

401 org_id_required / 403 invalid_org_id (direct HTTP only)

X-Org-Idを指定せずに(あるいは誤った値で)、直接/mcpエンドポイントを使用しています。Settings → API Keysから正確な組織IDをコピーするか、この設定が不要なローカルプロキシに切り替えてください。

429 rate_limit_exceeded

キーのレート制限を超えました。Retry-Afterヘッダーに示された時間だけ待つか、管理者に制限の緩和を依頼してください。

Tools not appearing

設定を編集した後、クライアントを完全に再起動してください。
JSON/TOMLの構文エラーがないか確認してください。
設定内のサーバー名が、参照している名前(通常はshanone)と一致しているか確認してください。
ローカルプロキシを使用している場合は、ターミナルで直接npx -y @duzzle/shanone-mcpを実行して、起動時のエラーを確認してください。

セキュリティのベストプラクティス

環境変数を使う

クライアントが対応している場合は、キーをコミットする設定ファイルに直接書き込む代わりに、環境変数を参照してください。

マシン/エージェントごとにキーに名前を付ける

そうすることで、1つを無効化しても他に影響が及びません。

定期的にローテーションする

期限が切れる前にSettings → API Keysから新しいキーを作成し、クライアント設定を更新してください。新しいキーで動作することを確認してから、古いキーを無効化します。

MCP

前提条件

ステップ1: APIキーを取得する

ステップ2: クライアントを設定する

プランと接続先の確認

Pythonプロキシ(代替手段)

接続を確認する

設定リファレンス

トラブルシューティング

セキュリティのベストプラクティス

次のステップ

Shanone MCPサーバー

ツールリファレンス

​前提条件

​ステップ1: APIキーを取得する

​ステップ2: クライアントを設定する

​プランと接続先の確認

​Pythonプロキシ(代替手段)

​接続を確認する

​設定リファレンス

​トラブルシューティング

​セキュリティのベストプラクティス

​次のステップ

Shanone MCPサーバー

ツールリファレンス

前提条件

ステップ1: APIキーを取得する

ステップ2: クライアントを設定する

プランと接続先の確認

Pythonプロキシ(代替手段)

接続を確認する

設定リファレンス

トラブルシューティング

セキュリティのベストプラクティス

次のステップ