Claude Code セットアップ

TWP の MCP サーバーを Claude Code に接続し、AI から TWP を操作できるようにするまでの手順です。「個人用 API キーの発行」→「Claude Code への登録」→「接続確認」の 3 ステップで完了します。

API キーを発行せず、TWP アカウントでログインして接続する（OAuth） こともできます。その場合は TWPアカウントでログインして接続する（OAuth） をご覧ください。

前提条件

• TWP アカウント：操作したい機能（プロジェクト・タスク等）の利用権限を持っていること。API キーの権限は、あなたのアカウントが持つ権限の範囲内でのみ有効です。
• Claude Code がインストール済み：ターミナルで次のコマンドが動作すること。

claude --version

まだの場合は Claude Code のインストール手順  を参照してください。

ステップ1: 個人用 API キーを発行する

1. TWP にログインします（本番: https://app.tocca.systems）。

2. 画面右上のアカウントメニューから 「プロフィール設定」 を開き、左メニューの 「APIキー」 を選びます。

   • 直接アクセスする場合の URL: https://app.tocca.systems/v1/profile/api-keys

3. 「新規作成」 をクリックします。

4. 次の項目を入力・選択します。

   項目	内容
   名前	用途がわかる名前（例: Claude Code）
   説明	任意（例: 開発PCのClaude Code用）
   パーミッション	このキーで許可する操作。必要なものだけを選択（後述）
   有効期限	無期限 / 7日間 / 30日間 / 90日間 / 1年間 / カスタム

5. 「作成」 をクリックすると、twpu_ で始まる API キーが表示されます。

重要：API キーの全文が表示されるのは、この作成直後の一度だけです。安全な場所にコピーして保管してください。閉じた後は再表示できず、その場合は新しいキーを作り直すことになります。

権限（スコープ）の選び方

権限は「リソース:操作」の形式です（例: task:read = タスク閲覧、task:write = タスク作成・更新）。task:* のように * を選ぶと、そのリソースの全操作を許可します。

日常的なプロジェクト・タスク運用であれば、以下のあたりが目安です。

他のエンドポイントを使う場合は、対応する権限も付与します。

最小権限の原則：不要な権限は付けないでください。閲覧しかしないなら :read のみ、といったように用途を絞ると、キーが漏洩した場合の被害を最小化できます。

ステップ2: Claude Code に登録する

登録方法は 2 通りあります。1台のPCで手早く使うなら方法A（CLI）、チームでリポジトリに設定を共有するなら方法B（.mcp.json） が便利です。

方法A: CLI コマンドで登録（推奨）

ターミナルで次のコマンドを実行します。twpu_xxxxxxxx の部分をステップ1で取得したキーに置き換えてください。

claude mcp add --transport http twp https://mcp.tocca.systems/api/mcp \
  --header "Authorization: Bearer twpu_xxxxxxxx"

• twp はこの接続の名前です。任意の名前を付けられます。
• すべてのプロジェクトで使いたい場合は --scope user を追加します（省略時は現在のプロジェクトのみ）。

claude mcp add --scope user --transport http twp https://mcp.tocca.systems/api/mcp \
  --header "Authorization: Bearer twpu_xxxxxxxx"

方法B: .mcp.json を編集して登録

プロジェクトのルートに .mcp.json を作成（または追記）します。チームで設定を共有したいときはこちらが便利です。

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

• "type": "http" は必須です（省略すると別種のサーバーとして扱われ、接続に失敗します）。
• API キーは直接書かず、環境変数 ${TWP_API_KEY} として展開させることを推奨します（キーをリポジトリにコミットしないため）。

環境変数を設定してから Claude Code を起動します。

export TWP_API_KEY=twpu_xxxxxxxx
claude

プロジェクトスコープの .mcp.json を初めて使うときは、Claude Code の起動時に「このサーバーを信頼するか」の承認を求められることがあります。/mcp から承認してください。

複数エンドポイントを登録する

TWP MCP サーバーは機能ごとにエンドポイントが分かれています（MCP連携 概要 のエンドポイント一覧を参照）。コア以外の機能を使いたい場合は、エンドポイントごとに別々の接続として登録します。名前（下記の twp-note など）は任意です。

claude mcp add --transport http twp-note https://mcp.tocca.systems/api/mcp/note \
  --header "Authorization: Bearer twpu_xxxxxxxx"
 
claude mcp add --transport http twp-hearing https://mcp.tocca.systems/api/mcp/hearing \
  --header "Authorization: Bearer twpu_xxxxxxxx"

.mcp.json の場合は mcpServers に並べて記述します。

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

• API キーは同じものを使い回せます（必要な権限がキーに付与されている必要があります）。
• 必要なエンドポイントだけを登録してください。登録数を増やすと、AI が選択できるツールの数も増えます。

ステップ3: 接続を確認する

登録済みサーバーの一覧と状態を確認します。

claude mcp list
claude mcp get twp

Claude Code のセッション内では、スラッシュコマンドで状態を確認できます。

/mcp

twp が connected（接続済み） と表示されれば成功です。接続できない場合は トラブルシューティング を確認してください。

使ってみる

接続できたら、Claude Code に自然文で指示してみましょう。

自分が担当しているタスクの一覧を見せて

プロジェクト「◯◯」に「動作確認」というタスクを作成して

AI が TWP のツールを呼び出し、結果を返します（操作の実行前に確認を求められる場合があります）。

TWPアカウントでログインして接続する（OAuth）

API キーを発行・管理する代わりに、Claude Code から TWP アカウントでログインして接続する方法です。キーをファイルや環境変数に保存する必要がありません。

1. ヘッダーを付けずに登録する

--header を付けずに登録します。

claude mcp add --transport http twp https://mcp.tocca.systems/api/mcp

.mcp.json の場合は headers を書きません。

{
  "mcpServers": {
    "twp": {
      "type": "http",
      "url": "https://mcp.tocca.systems/api/mcp"
    }
  }
}

2. Claude Code からログインする

1. Claude Code のセッション内で /mcp を実行し、twp を選んで認証（Authenticate）を実行します。
2. ブラウザで TWP の 「ログイン」 画面が開きます。テナントコード・メールアドレス・パスワード を入力して 「ログイン」 をクリックします。
3. ログインが完了すると Claude Code に戻り、twp が connected（接続済み） になります。TWP 側に別途「許可する」画面は表示されません。

ログイン状態の更新は Claude Code が自動で行います。ログインし直したい場合は、/mcp から twp を選んで再度認証してください。

3. OAuth 接続で許可する操作を設定する（任意）

OAuth で接続した AI クライアントに許可する操作は、TWP の 「プロフィール設定」→「動的OAuth設定」 で設定します。

• 直接アクセスする場合の URL: https://app.tocca.systems/v1/profile/settings/dynamic-oauth
• 初期状態（未設定）では、すべての操作が許可されています。
• 操作を絞りたい場合は 「権限を個別に設定する」 にチェックを入れ、許可する操作（例: 「プロジェクト閲覧」「タスク編集」）を選んで 「保存」 をクリックします。チェックを外した操作は、OAuth 接続からは実行できなくなります。
• この設定は、あなたのアカウントで OAuth 接続したすべての AI クライアントに共通で適用されます（API キーの権限とは別に管理されます）。
• API キーと同様、あなたのアカウントの利用権限の範囲を超える操作はできません。

許可されていない操作を AI が実行しようとすると、ツールの呼び出しが API error 403: Insufficient permissions で失敗します。

複数エンドポイントを OAuth で登録する

コア以外のエンドポイントも、同じように --header なしで登録できます。エンドポイントごとに /mcp から認証してください。

claude mcp add --transport http twp-note https://mcp.tocca.systems/api/mcp/note

管理・運用

API キーのローテーション

セキュリティ強化のため、API キーは定期的に再発行することを推奨します。

1. TWP の「プロフィール設定」→「APIキー」で新しいキーを作成する
2. Claude Code の設定（CLI で再登録、または .mcp.json / 環境変数）を新しいキーに更新する
3. 古いキーを削除する

不要になったキー・漏洩の疑いがあるキーは、「プロフィール設定」→「APIキー」から速やかに無効化または削除してください。無効化・削除したキーを使うと、ツールの呼び出しが API error 403: {"message":"Forbidden"} で失敗します（MCP サーバーへの接続自体は、キーの形式が正しければ connected と表示されます）。

API キーの取り扱い

• API キーはパスワードと同等の機密情報です。他人に共有しないでください。
• .mcp.json に API キーを直接書かず、環境変数経由で渡してください。
• API キーをバージョン管理（git）にコミットしないでください。