セットアップガイド

このガイドでは、Phennecの初期セットアップから各ツールとの連携、そしてAIエージェント（Cursor）での利用開始までの手順を説明します。

1. アカウント作成

コントロールパネルにアクセスします。
Sign Up をクリックし、必要な情報を入力してアカウントを作成します。

2. プロジェクト作成

サイドバーの Projects をクリックします。
Add Project をクリックします。
プロジェクト名を入力し、作成を完了します。

3. コネクター追加

作成したプロジェクトの画面から Connectors > Create Connector をクリックしてください。

GitLabの連携

リポジトリを連携するには、GitLabのPersonal Access Tokenが必要です。

GitLab 側

GitLab にログイン
Profile → Edit Profile → Access Tokens を開く
Add new token をクリック（※）
- Scopes で read_repository と read_api を選択
Create token をクリックし、生成されたトークンをコピーする

Phennec コントロールパネル側

GitLab コネクターを作成する
GitLabリポジトリのURL を プロジェクトURL として入力し、Personal Access Token を トークン に貼り付ける
Create を押下する

※ 連携には対象プロジェクトの Maintainer または Owner 権限が必要で、Personal Access Token で接続できない場合はプロジェクト内の Settings → Access Tokens から Project Access Token を作成してください

GitHubの連携

リポジトリを連携するには、GitHub の Personal access token (classic) と repo スコープが必要です。

GitHub 側

Settings（設定） → Developer settings（開発者設定） → Personal access tokens を開く
Personal access token (classic) を作成する
repo スコープ（Full control of private repositories）を選択する
トークンを生成し、コピーする

Phennec コントロールパネル側

GitHub コネクターを作成する
リポジトリの URL とトークンを入力する
Create を押下する

※ 特定のリポジトリにアクセスを限定したい場合は、代わりに Fine-grained personal access token を利用できます。その場合は、Repository access で Only select repositories を選択し、対象リポジトリを指定したうえで、必要な読み取り専用権限のみを付与してください。対象リポジトリが Organization 所有の場合は、Organization の承認やトークンポリシーの許可が必要なことがあります。

Google Driveの連携

Google DriveのフォルダをPhennecのサービスアカウントに共有する必要があります。

Google Drive 側

連携したい Google Drive のフォルダを開く
共有をクリック
以下のアカウントを 編集者 として追加する:
syncer@phennec.iam.gserviceaccount.com

Phennec コントロールパネル側

Google Drive コネクターを作成する
共有した Google Drive フォルダの URL を プロジェクトURL として入力する
Create を押下する

Backlogの連携

Backlog 側

連携したい Backlog プロジェクトの URL をコピーする
個人設定 → API → 登録を開く
APIキーを発行し、コピーする

Phennec コントロールパネル側

Backlog コネクターを作成する
Backlog プロジェクトの URL と APIキーを入力する
Create を押下する

Notionの連携

ページを連携するには、Notionインテグレーションの作成が必要です。

Notion 側

設定 → インテグレーション を開く（※）
新しいインテグレーション をクリックして作成する
作成したインテグレーションの設定画面を開く
シークレットトークンを表示し、コピーする
Phennec と連携したい Notion の親ページを開く
ページ右上の … をクリック
接続を選択し、作成したインテグレーションを追加する

Phennec コントロールパネル側

Notion コネクターを作成する
NotionページのURL を プロジェクトURL として入力し、シークレットトークンを トークン に貼り付ける
Create を押下する

※ インテグレーションを作成する権限がない場合、組織内で権限を持つ方にシークレットトークンの共有を依頼してください

DocBaseの連携

DocBase 側

連携したい DocBase グループの URL をコピーする
アカウント設定 → アクセストークン → トークンを作成 を開く
以下を設定する
- 操作対象グループ：連携対象のグループを選択
- スコープ：読み取り
トークンを作成し、コピーする

Phennec コントロールパネル側

DocBase コネクターを作成する
DocBase グループの URL とアクセストークンを入力する
Create を押下する

Slackの連携

※ Slack アプリの権限（初回設定）

Phennec のコントロールパネルで Slack コネクター を作成すると、Slack の認証画面にリダイレクトされ、Slack アプリ phennec へのワークスペースアクセス許可が求められます。

この認証は コネクター（Slack チャンネル）ごと に必要です。新しい Slack コネクターを作成するたびに 認証を完了してください。

認証画面でアプリを追加できない場合は、Slack の ワークスペース管理者 に phennec アプリの承認またはインストールを依頼してください。管理者による対応後、Slack コネクターを再度作成すると、通常どおり利用できます。

Phennec が検索対象にする各 Slack チャンネルに、Phennec アプリを追加してください。追加されていないチャンネルのメッセージはコネクターから参照できません。

Slack 側

対象のチャンネルを開く
チャンネルのURLをコピーする
チャンネル詳細を開く → インテグレーション → アプリを追加する
「Phennec」を検索してチャンネルに追加する

Phennec コントロールパネル側

Slack コネクターを作成する
Slack チャンネルの URL を入力する
作成を押下する

4. Cursorでの利用 (MCP)

Phennec コントロールパネルで 左下のプロフィールアイコン → MCP をクリックし、MCP設定画面を開く
Quick Setup リンクをクリック
ブラウザがCursorを開く許可を求めた場合は許可する
Tools & MCP 設定画面に遷移し、Phennec MCPの詳細と個人トークンが自動入力されていることを確認する
Install をクリックしてセットアップを完了する

この操作は一度だけ行えば完了です。

インストール後、Cursorのチャット画面（CMD+L）を開き、プロンプトに phennec と入れるだけでコンテキストが自動的に取得されます。
例: phennec @Codebase ログインページの仕組みを教えて

複数のプロジェクトがある場合、グローバルMCP接続を通じてすべてのプロジェクトにアクセスできます。コンテキストを正確に保つため、最初のプロンプトでプロジェクト名を指定し、プロジェクトごとに別のチャットを使用してください。

Phennecがドキュメントやコードから常に最新かつ関連性の高いコンテキストを自動的に取得し、Cursorなどご利用のツール内のAIエージェントに提供します。

5. チーム管理（権限・アクセス）

組織レベル管理

組織は、チーム・クライアント・環境ごとに分離して管理するためのトップレベルのワークスペースです。社内用・個人用と、共有用・案件用で組織を分けて運用することを推奨しています。

組織レベルのユーザーは、その組織内のすべてのプロジェクト・グループ・コネクターへアクセスでき、作成／編集／削除権限も持ちます。そのため、組織レベルの権限付与は慎重に行ってください。
閲覧のみの権限を付与したい場合は、組織レベルではなくプロジェクトレベルでユーザーを追加することを推奨しています。
組織を切り替える（左下のプロフィールアイコン → 組織を切り替え）ことで、コントロールパネルに表示されるプロジェクト／グループ／コネクターが切り替わります。

組織の削除について

組織を削除できるのは、その組織の作成者のみです。
組織を削除すると、その組織配下のプロジェクトおよびコネクターは完全に削除されます。

プロジェクトレベル管理

プロジェクトは、コネクターと検索対象データを管理する個別のワークスペースです。

プロジェクトに直接追加されたユーザーは、デフォルトで閲覧権限のみを持ちます。
プロジェクト作成者以外のユーザーは、コネクターの追加／編集、ユーザー管理、プロジェクトの削除を行うことはできません。
複数ユーザーにプロジェクト管理権限を付与したい場合は、組織レベルで追加することを検討してください。詳しくは上記の組織レベル管理を参照してください。

グループレベル管理

グループは、プロジェクトやサブグループを整理するためのフォルダのような機能です。

グループレベルで追加されたコネクターは、配下のすべての子プロジェクトで利用可能です。
グループレベルのユーザーは、グループ配下のプロジェクトに対して閲覧権限のみを持ちます。
管理者ではないグループメンバーは、コネクターの追加／編集、ユーザー管理、プロジェクト／グループ管理を行うことはできません。

6. トラブルシューティング

コネクターがうまく動かない

以下をお試しください。

① MCPクライアントを再起動する

MCPクライアントを再起動し、新しいチャットで再度お試しください。

② MCP接続を更新する

クライアント側で Phennec MCP の設定を更新すると、接続が復旧することがあります。

Cursor： 設定 → MCP で Phennec MCP をオフにしてから、再度オンにします。
その他のMCPクライアント： アプリのMCP（または連携）設定で Phennec をいったん削除し、Phennecコントロールパネル（左下のプロフィールアイコン → MCP、またはプロジェクト画面のプロジェクトスコープトークン）に表示されているURLとトークンを使って再追加してください。

③ MCPトークンがワークスペースのものと一致しているか確認する

クライアント（Cursor / Gemini など）で使用しているトークンが、Phennecワークスペースに表示されているトークンと一致していることを確認してください。

グローバルトークン：左下のプロフィールアイコン → MCP で確認できます。
プロジェクトスコープのトークン：アクセス対象は一度に1つのプロジェクトに限定されます。各プロジェクト画面で確認できます（プロフィールのMCP画面には表示されません）。

④ コネクターで使っているPAT（APIキー）を確認する

コネクターは、連携元のツールで発行した資格情報（PAT（Personal Access Token） や APIキー など）で登録されています。

次の点を確認してください。

トークンやキーが削除・期限切れ・失効していないか
必要な権限やスコープが引き続き付与されているか

※ 各コネクターの必要な権限は「コネクターを作成」画面に記載されています。

追加された組織のプロジェクトにアクセスできない

正しい組織へ切り替えているかご確認ください。

コントロールパネルで以下を操作してください。

左下のプロフィールアイコン → 組織を切り替え
追加された組織を一覧から選択してください。

追加されたプロジェクトでコネクターの追加・編集ができない

デフォルトでは、コネクターやユーザーの追加・編集権限はプロジェクト作成者のみが持っています。

複数ユーザーに同様の権限を付与したい場合は、コントロールパネルから対象ユーザーを組織へ追加してください。

左下のプロフィールアイコン → 組織を切り替え → 組織を管理

ご注意ください：ユーザーを組織へ追加すると、その組織内のすべてのプロジェクトへアクセス可能になります。個人用プロジェクトを分けたい場合は、共有・案件用に別組織を作成する運用を推奨しています。

Google Driveコネクターがうまく動かない

以下をお試しください。

① 共有設定の確認

Drive フォルダが次の Syncer アカウントに編集者権限で共有されているかをご確認ください。

syncer@phennec.iam.gserviceaccount.com

補足

大きなファイルは、同期に最大10分程度かかる場合があります
10分以上経っても反映されない場合は、同期が停止している可能性がありますのでご連絡ください

Slackコネクターが同期できない

Phennec アプリをチャンネルに追加するまで、Slack コネクターは同期されません。 先にコネクター追加の Slackの連携 の手順に従って対象チャンネルにアプリを追加し、その後 Slack コネクターを再度作成してみてください。

Phennec に最新の情報を尋ねたのに、古い結果に見える

Phennec の回答が期待より古いように感じるときは、次の順で試してください。

① 新しいチャットで聞き直す

MCP クライアントで新しいチャットを開き、同じ内容でもう一度聞いてみてください。長いスレッドでは、古い文脈の影響が残ることがあります。

② コントロールパネルでコネクターを再同期する

Phennec コントロールパネルを開き、対象のプロジェクトを開く
該当コネクターの ••• メニューをクリック
再同期を選択します。

同期が完了したら、新しいチャットでプロンプトを再度試してください。

なぜそうなるか

Phennec は 同期・インデックス済み のデータを検索します。連携先を常にリアルタイムで読むわけではないため、再同期で取り込むまで古いままに見えることがあります。また、必ずしも最新状態になるとは限りません。

特定のメッセージやファイルにアクセスできない

URLやファイル名を指定した検索には対応していますが、コネクター（Slack / Drive / GitHub など）やデータのインデックス状況によっては、完全一致での検索が安定しない場合があります。Phennecはセマンティック検索（意味ベース）を採用しているため、内容や文脈に基づいた検索の方が、より高い精度で見つかりやすくなります。

GitHub / GitLab のコネクターで特定のコードを検索できない

GitHub / GitLabコネクターは、すべてのコードを対象にしているわけではありません。主にセマンティック検索の対象となるのは以下です。

Issue / チケット
コメント
テキスト形式のファイル（例：README、.md、.txt など）

そのため、次のケースには対応していません。

特定の関数や実装を直接検索すること
Phennec 単体からリポジトリ全体の構成を推測すること

補足（おすすめの使い方）

使用している MCP クライアントでリポジトリを開き、プロンプトでファイルやパスを直接参照してください。Phennec MCP が同期したインデックス情報と、クライアントがアクセスできるワークスペース上のソースを組み合わせることで、コードを扱う場合でも Phennec MCP をより十分に活用できます

「phennec」と書いているのにMCPが呼ばれない

① プロンプトの明示

MCPが正しく呼び出されない場合は、以下のように明示的に記述してください。

Phennec MCPを使って〜（〜の部分にやってほしいことを書く）

明示することで、ツールが選択されやすくなります。

② 推奨設定（Agent Rules）

agents.md または .cursor にルールを追加し、プロンプト内で「phennec」と記載された場合に、ワークスペース検索ではなくMCPツールが優先的に実行されるよう設定してください。