Skip to Content
MCP連携（Claude Code）トラブルシューティング

トラブルシューティング

MCP サーバーに接続できない、ツールが動かないときの確認ポイントです。まずは Claude Code のセッション内で /mcp を実行し、twp の状態と表示されているエラーメッセージを確認してください。

接続できない（connected にならない）

type の指定漏れ

.mcp.json で登録している場合、"type": "http" が指定されているか確認してください。省略すると別種のサーバーとして扱われ、接続に失敗します。

{
  "mcpServers": {
    "twp": {
      "type": "http",
      "url": "https://mcp.tocca.systems/api/mcp",
      "headers": { "Authorization": "Bearer ${TWP_API_KEY}" }
    }
  }
}

環境変数が展開されていない

${TWP_API_KEY} を使っている場合、Claude Code を起動したシェルで環境変数が設定されているか確認します。

echo $TWP_API_KEY   # twpu_ で始まる値が表示されるか

未設定だと、そのままの文字列が送られて認証に失敗します。設定してから Claude Code を起動し直してください。

URL の確認

エンドポイント URL が正しいか確認してください（コアは https://mcp.tocca.systems/api/mcp）。末尾のパスや https になっているかに注意します。

認証エラー（401 / Unauthorized）

API キーが正しく送られていない、または無効になっています。

  • Authorization ヘッダーの形式：Bearer に続けてキーを指定します（例: Authorization: Bearer twpu_...）。Bearer とキーの間に半角スペースが必要です。
  • キーの種類：MCP では個人用 API キー（twpu_） を使用します。組織 API キー（twpk_）は使えません。
  • キーが有効か：TWP の「APIキー管理」で、対象キーが有効（削除・無効化されていない）で、有効期限が切れていないか確認します。
  • キーの前後の空白：コピー時に余分な空白や改行が混入していないか確認します。

キーを再発行した場合は、Claude Code 側の設定（CLI で再登録、または環境変数）も新しいキーに更新してください。

API キーを無効化・削除した場合、反映まで最大 1 分程度かかることがあります。

権限エラー（403 / Forbidden）

接続はできているが、特定の操作だけが拒否される場合は権限（スコープ）不足です。

  • API キーに、その操作に必要な権限が付与されているか確認します（例: タスク作成には task:write または task:*）。
  • 権限を追加するには、TWP の「APIキー管理」で新しいキーを作成して付け替えます（既存キーの権限は、実装によっては編集画面から変更できます）。
  • API キーの権限はあなたのアカウントの利用権限の範囲内でのみ有効です。アカウント自体にその機能の権限がない場合は、キーに権限を付けても操作できません。管理者にアカウント権限の付与を依頼してください。

ツールが表示されない・呼び出されない

  • 目的の機能が別エンドポイントにある可能性があります。レポートは /api/mcp/report、ノートは /api/mcp/note、ヒアリングは /api/mcp/hearing、取引は /api/mcp/sales、Backlog / Microsoft 365 は /api/mcp/personal です。必要なエンドポイントを追加で登録してください（利用できるツール 参照）。
  • ノート・ヒアリングのツールが急に表示されなくなった場合：これらのツールはコアエンドポイント（/api/mcp）から専用エンドポイント（/api/mcp/note・/api/mcp/hearing）に移動しました。専用エンドポイントを追加で登録してください（Claude Code セットアップ の「複数エンドポイントを登録する」参照）。
  • Backlog / Microsoft 365 のツールは、TWP 側で各サービスとの連携設定が完了している必要があります。

それでも解決しない場合

  • claude mcp get twp で登録内容（URL・ヘッダー）を再確認してください。
  • Claude Code を最新版に更新してください（claude --version でバージョンを確認）。
  • 上記で解決しない場合は、TWP 管理画面内のサポート機能からお問い合わせください。
Last updated on
利用できるツール概要