トラブルシューティング

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）

MCP サーバーは、接続時にはキーの形式だけを確認します。Authorization ヘッダーが無い、または twpu_ で始まらないキーを送ると、接続の時点で 401（invalid_token）になります。

ヘッダーを付けずに登録している（OAuth で接続する）場合、401 は「ログインが必要」という意味です。Claude Code では /mcp から twp を選んで認証（ログイン）してください（TWPアカウントでログインして接続する（OAuth）参照）。

Authorization ヘッダーの形式：Bearer に続けてキーを指定します（例: Authorization: Bearer twpu_...）。Bearer とキーの間に半角スペースが必要です。
キーの種類：MCP では個人用 API キー（twpu_） を使用します。組織 API キー（twpk_）は使えません。
キーの前後の空白：コピー時に余分な空白や改行が混入していないか確認します。

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

接続はできるが、すべてのツールが `API error 403: {"message":"Forbidden"}` になる

キーの形式は正しいが、キーそのものが使えない状態です（MCP サーバーへの接続は connected のまま、ツールを呼んだ時点で失敗します）。

TWP の「プロフィール設定」→「APIキー」で、対象キーが有効（削除・無効化されていない）で、有効期限が切れていないか確認します。
キーの一部が欠けていないか（コピー漏れ）確認します。

API キーを無効化・削除してから実際に拒否されるまで、最大 1 分程度かかることがあります。

権限エラー（403 / Forbidden）

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

API キーに、その操作に必要な権限が付与されているか確認します（例: タスク作成には task:write または task:*）。
権限を追加するには、TWP の「プロフィール設定」→「APIキー」の一覧から対象キーを開き、パーミッションを変更して保存します（新しいキーを作成して付け替えても構いません）。変更の反映には最大1分程度かかることがあります。
API キーの権限はあなたのアカウントの利用権限の範囲内でのみ有効です。アカウント自体にその機能の権限がない場合は、キーに権限を付けても操作できません。管理者にアカウント権限の付与を依頼してください。

OAuth で接続している場合の権限エラー（`API error 403: Insufficient permissions`）

TWP アカウントでログインして（OAuth で）接続している場合、許可する操作は API キーではなく 「プロフィール設定」→「動的OAuth設定」 で決まります。

「権限を個別に設定する」にチェックが入っている場合、チェックの付いていない操作は API error 403: Insufficient permissions で失敗します。必要な操作にチェックを入れて 「保存」 してください。
設定を変えても解決しない場合は、アカウント自体にその機能の利用権限があるか管理者に確認してください。
すべてのツールが API error 403: {"message":"Forbidden"} になる場合は、ログイン状態が無効になっています。/mcp から twp を選んで再度認証（ログイン）してください。

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

目的の機能が別エンドポイントにある可能性があります。レポートは /api/mcp/report、ノートは /api/mcp/note、ヒアリングは /api/mcp/hearing、取引は /api/mcp/sales、アプローチ先は /api/mcp/prospect、顧客は /api/mcp/customer、勤怠は /api/mcp/attendance、予実管理の按分設定・目標は /api/mcp/budget、サポート依頼は /api/mcp/support、工程・品質チェック項目は /api/mcp/project-master、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 管理画面内のサポート機能からお問い合わせください。