Skip to main content

​
接続の問題

リクエストにAPIキーが含まれていません。MCPクライアントの設定に、MCPセットアップに記載の通りAuthorization: Bearer sh_xxx(またはX-API-Key: sh_xxx)が含まれているか確認してください。ローカルのstdioプロキシを使っている場合は、envブロックにSHANONE_API_KEYが実際に設定されているか確認してください——環境変数の欠落が最も多い原因です。
キーの形式が不正、無効化済み、または期限切れです。Settings → API Keysから新しいキーを作成し、クライアントの設定を更新してください。平文のキーは作成時に一度しか表示されないことを忘れないでください——失った場合はそのキーを無効化し、新しいものを作成してください。
ローカルプロキシを使わず、https://app.shanone.ai/mcpに直接接続しています。このエンドポイントはAPIキーとX-Org-Idヘッダーの両方を必要とします——APIキーだけでは不十分です。Settings → API Keysから組織IDをコピーし、X-Org-Idとして追加してください(カスタムヘッダーを送れないクライアントの場合はURLに?org_id=...を付加します)。ローカルのstdioプロキシ(@duzzle/shanone-mcp)ではこれは不要で、APIキーのみで動作します。
APIキーのレート制限(デフォルトで60リクエスト/分、10,000リクエスト/日)を超えました。レスポンスにはRetry-Afterヘッダーが含まれるので、その時間だけ待ってから再試行してください。これが頻発する場合は、Root/管理者にSettings → API Keysでキーのrate_limitを上げてもらうよう依頼してください。
  1. 設定を編集した後は、MCPクライアントを完全に再起動してください(リロードだけでは不十分な場合があります)。
  2. 設定ファイルにJSON構文エラーがないか確認してください——末尾のカンマがあると、多くのクライアントでmcpServersブロック全体が静かに壊れます。
  3. ツール呼び出しで指定しているサーバー名が、設定ファイルのキー(通常はshanone)と一致しているか確認してください。
  4. ローカルプロキシを使っている場合は、npx -y @duzzle/shanone-mcpをターミナルで直接実行し、起動時エラーを確認してください。

​
認証とOAuth

各サービスのOAuth接続は、あなたのセッションではなくShanoneのユーザーに紐づいています。エージェントが使っているAPIキーの同じShanoneアカウントでサインインした状態でOAuthフローを完了したか確認してください——チームメイトとしてログインした状態でSlackを接続しても、あなたのキーには反映されません。
そのサービスの保存済みOAuthトークンが期限切れになった、または上流(Slack/Googleなどのアプリ側)でアクセスが取り消されたことを意味します。レスポンスに含まれる新しいconnect_linkをたどって再認可してください——その後、更新されたトークンはShanoneが自動的に保存します。

​
権限エラー

Permission Vendorのツール群(shanone_set_user_tool_permission、shanone_set_user_service_permission、shanone_get_permission_summary、shanone_batch_set_user_permissions、shanone_list_user_tool_permissions)は、呼び出す側がRootユーザーであること、またはtool-permissions:ManageOthersポリシーアクションを明示的に委任されたSA2ユーザーであることを要求します。委任されたSA2ユーザーは、それに加えてRootユーザーの権限を変更することはできません。チームメイトのアクセスを管理する必要がある場合は、組織のRoot管理者にそのポリシーアクションの付与を依頼してください。
ツール単位の権限オーバーライドは常にサービス単位のオーバーライドより優先され、サービス単位のオーバーライドはロールのデフォルト設定より優先されます。Root/SA2の管理者に、あなたのuser_idに対してshanone_get_permission_summaryを実行してもらい、正確に何が有効になっているか確認してもらってください。生のオーバーライド一覧が必要な場合はshanone_list_user_tool_permissionsを使います。
これは、Shanoneのカタログに(まだ)存在しないツール名やサービス名に対して権限を設定しようとしたときに表示されます——多くの場合は入力ミスです。shanone_list_servicesやshanone_search_toolsで正確な名前を再確認してください。なお、そのオーバーライドはそのまま保存され、該当する名前が登録された時点で自動的に適用されます。

​
ツールの実行結果が想定と異なる

shanone_search_toolsのクエリを、単なるサービス名ではなく、より具体的にタスクに沿ったものにしてください(ベストプラクティスを参照)——これはSlack、Stripe、HubSpotのような大規模なインテグレーションで特に起こりやすく、多数のツールがキーワードを共有しているためです。
破壊的操作やリスクの高い一部のツールは、明示的な確認ステップを必要とします。実行を確定したい場合は、同じ引数に加えてJSONペイロードに"confirm": trueを付けてshanone_execute_toolを再実行してください。
更新後のshanone_execute_tool.argumentsにはJSONオブジェクトを渡します。例: {"channel": "#general", "text": "hi"}。引数なしは{}です。配列・null・スカラーは受け付けません。旧形式のJSON文字列を使う場合は、有効なオブジェクトを表すJSONである必要があります。文字列型を要求するエラーが続く場合は、接続先とパッケージのバージョンを確認し、再接続してtools/listを更新してください。

​
さらにサポートが必要な場合

MCPツールリファレンス

すべてのツールのパラメータとエラーレスポンスの完全なリファレンス

サポート

Shanoneチームに連絡する

​
バグを報告する

問題を報告する際は、以下を含めてください。
  • 呼び出した正確なツール名と引数(機密情報は伏せてください)
  • reasonフィールドを含む、レスポンスの全文
  • 使用しているクライアント(Cursor、Claude Code、直接HTTPなど)、およびローカルプロキシか直接/mcpエンドポイントかどちらを使っているか
  • 試した場合、Shanone Webダッシュボードのツールテスターから同じ呼び出しが動作するかどうか