セットアップガイド

このガイドでは、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. トラブルシューティング

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

以下をお試しください。

① 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ツールが優先的に実行されるよう設定してください。