Setup Guide

This guide walks you through Phennec's initial setup — from creating your account to connecting your tools and getting context flowing to your AI agent.

1. Create an Account

Access the Phennec Control Panel.
Click Sign Up and fill in your details.

2. Create a Project

Click Projects in the sidebar.
Click Add Project.
Enter a project name and complete creation.

3. Add Connectors

From your newly created project, click Connectors > Create Connector.

GitLab Integration

You'll need a GitLab Personal Access Token to connect your repositories.

In GitLab

Log in to GitLab
Open Profile → Edit Profile → Access Tokens
Click Add new token (*)
- Select scopes read_repository and read_api
Click Create token and copy the generated token

In the Phennec Control Panel

Create a GitLab connector
Paste the repository URL as the Project URL, and the access token into the token field
Click Create

* You must have Maintainer or Owner permissions for the target project. If a Personal Access Token does not work, create a Project Access Token from Settings → Access Tokens within the project.

GitHub Integration

You'll need a GitHub personal access token (classic) with the repo scope to connect your repositories.

In GitHub

Open Settings → Developer settings → Personal access tokens
Create a Personal access token (classic)
Select the repo scope (full control of private repositories)
Generate the token and copy it

In the Phennec Control Panel

Create a GitHub connector
Enter the repository URL and token
Click Create

* If you want to limit access to a specific repository, you can use a Fine-grained personal access token instead. In that case, set Repository access to Only select repositories, choose the target repository, and grant only the required read-only permissions. If the repository belongs to an organization, organization approval or token policy may be required.

Google Drive Integration

You'll need to share your Google Drive folder with Phennec's service account.

In Google Drive

Open the Google Drive folder you want to connect
Click Share
Add the following account as Editor:
syncer@phennec.iam.gserviceaccount.com

In the Phennec Control Panel

Create a Google Drive connector
Paste the Google Drive folder URL as the Project URL
Click Create

Backlog Integration

In Backlog

Copy the URL of the Backlog project you want to connect
Open Personal Settings → API → Register
Generate an API key and copy it

In the Phennec Control Panel

Create a Backlog connector
Enter the Backlog project URL and the API key
Click Create

Notion Integration

You'll need to create a Notion integration to connect your pages.

In Notion

Open Settings → Integrations (*)
Click New Integration to create an integration
Open your newly created integration's settings page
Click Show and copy the secret token
Open the parent Notion page you want to connect to Phennec
Click the ••• menu in the top-right corner of the page
Select Connections, then select the integration you created

In the Phennec Control Panel

Create a Notion connector
Paste the Notion page URL as the Project URL, and the secret token into the token field
Click Create

* If you do not have permission to create Notion integrations, ask someone in your organization to provide the secret token.

DocBase Integration

In DocBase

Copy the URL of the DocBase group you want to connect
Open Account Settings → Access Tokens → Create Token
Configure the following:
- Target Group: Select the group you want to connect
- Scopes: Read-only
Create the token and copy it

In the Phennec Control Panel

Create a DocBase connector
Enter the DocBase group URL and the access token
Click Create

Slack Integration

Slack app permissions (first-time setup)

When you create a Slack connector in the Phennec control panel, Slack redirects you to its authorization screen. There you grant the phennec Slack app access to your workspace.

That authorization flow is required per Slack connector (each linked channel). Complete it every time you create a new Slack connector.

If you cannot approve or install the app from the authorization screen, ask your Slack workspace administrator to approve or install the phennec app. After that, try creating the Slack connector again—it should work as expected.

Add the Phennec app to each Slack channel you want Phennec to search. Without it, messages in that channel will not be available to the connector.

In Slack

Open the target channel
Copy the channel URL
Go to Channel Details → Integrations → Add Apps
Search for Phennec and add it to the channel

In the Phennec Control Panel

Create a Slack connector
Enter the Slack channel URL
Click Create

4. Setup with Cursor (MCP)

In the Phennec Control Panel, click the bottom-left profile icon → MCP to open the MCP configuration screen
Click the Quick Setup link
If prompted, allow your browser to open Cursor
Confirm you are directed to the Tools & MCP settings screen, with the Phennec MCP details and your personal token pre-filled
Click Install to complete the setup

This only needs to be done once.

Once installed, open the Cursor chat (CMD+L) and mention phennec in your prompt to pull in context automatically.
Example: phennec @Codebase How does the login page work?

If you have multiple projects, the global MCP connection provides access to all of them. To keep context accurate, include the project name in your initial prompt and use a separate chat per project.

Phennec automatically pulls the most up-to-date, relevant context from your docs and code and delivers it to the AI agent inside Cursor or any other tool you use with Phennec.

5. Team Management (Permissions and Access)

Organizations

Organizations function as top-level workspaces used to separate teams, clients, or environments. We recommend creating separate organizations for internal/private work and shared/client work.

Organization-level users have access to all projects, groups, and connectors within the organization, including create/edit/delete permissions. Please be careful when granting organization-level access.
If you would like a user to have read-only access, we recommend adding them at the project level instead.
Switching organizations (bottom-left profile icon → Switch Organization) changes the projects/groups/connectors visible in the control panel.

Deleting an Organization

Only the creator of the organization can delete it.
Deleting an organization will permanently delete all projects and connectors created under that organization.

Projects

Projects are individual workspaces where connectors and searchable data are managed.

Users added directly to a project have read-only access by default.
Non-project-creators cannot add/edit connectors, manage users, or delete the project.
If you would like multiple users to manage a project, consider adding them at the organization level instead. See the Organizations section above.

Groups

Groups function as folders used to organize projects and subgroups.

Group-level connectors are available to all child projects within the group hierarchy.
Group-level users have read-only access to projects within the group hierarchy.
Non-admin group members cannot add/edit connectors, manage users, or manage projects/groups.

6. Troubleshooting

Connector connection issues

Try the following.

① Restart your MCP client

Restart your MCP client and try again in a new chat.

② Refresh the MCP connection

Refreshing the Phennec MCP entry in your client often clears a stuck connection.

Cursor: Under Settings → MCP, toggle Phennec MCP off, then on again.
Other MCP clients: Open your app’s MCP or integrations settings, remove the Phennec server, then add it again using the server URL and token from the Phennec control panel (bottom-left profile icon → MCP, or your project screen for project-scoped tokens).

③ Verify your MCP token matches your workspace

Ensure the token you use in the client (Cursor, Gemini, etc.) matches the one shown in your Phennec workspace.

Global tokens: Open the bottom-left profile icon → MCP.
Project-scoped tokens: Access is limited to one project at a time. These tokens are shown on each project screen (not under the profile MCP menu).

④ Check the PAT connected to your connectors

Each connector is set up with credentials from the source tool (often a Personal Access Token (PAT) or an API key).

Check that:

The token or key has not expired or been revoked
Required permissions or scopes are still granted

※ Required permissions for each connector are listed on the “Create connector” screen.

I can't access the projects of an organization I was added to

Please make sure you have switched to the correct organization.

In the control panel:

bottom-left profile icon → Switch Organization
Select the organization you were added to from the list.

I can't add/edit connectors for a project I was added to

By default, only the project creator has permission to add/edit connectors and users.

To allow multiple users to manage connectors/users, add them to your organization from the control panel:

bottom-left profile icon → Switch Organization → Manage Organizations

Please note: Adding a user to your organization will give them access to all projects within that organization. We recommend creating a separate organization for shared/client projects if you want to keep private projects separated.

Google Drive connector issues

Try the following.

① Check sharing settings

Confirm that your Drive folder is shared with the Syncer account below with Editor permissions:

syncer@phennec.iam.gserviceaccount.com

Notes

Large files may take up to ~10 minutes to sync
If data is still not reflected after more than 10 minutes, syncing may have stopped — please contact support

Slack connector sync issues

The Slack connector will not sync until the Phennec app is added to each channel you want Phennec to read. Add the app to the channel first (see Slack Integration under Add Connectors), then try creating the Slack connector again.

Outdated Phennec results

If Phennec’s answers feel behind what you expect, try the steps below.

① Try a new chat

Start a new chat in your MCP client and ask again. Long conversations can sometimes keep older context at the top.

② Re-sync the connector in the control panel

Open the Phennec control panel and select your project
Click the ••• menu on the connector you care about
Select re-sync.

Wait until the sync finishes, then try your prompt again in a new chat.

Why this happens

Phennec searches synced, indexed content—it isn’t reading your tools live—so you won’t always get the absolute freshest information until a sync has pulled new data in.

Specific message or file access issues

Phennec supports URL- and filename-based lookups, but depending on the connector (Slack / Drive / GitHub, etc.) and indexing state, exact-match searches may not be reliable. Phennec uses semantic (meaning-based) search, so searches grounded in content and context tend to match more accurately.

GitHub/GitLab code search limitations

GitHub / GitLab connectors do not index all code paths. Typical semantic-search coverage includes:

Issues / tickets
Comments
Plain-text files such as README, .md, and .txt

Therefore, the following cases are not supported:

Searching for a specific function or implementation directly
Inferring overall repository layout from Phennec alone

Recommended Usage

Open the repository in your MCP client (for example Cursor) and reference files or paths directly in your prompts. That combines Phennec’s indexed context with the client’s access to your working tree—this is the usual way to get the fullest Phennec MCP experience when you need real code in the loop

Phennec MCP is not invoked from prompts

① Make your prompt explicit

If MCP still does not run, phrase the request explicitly, for example:

Use the Phennec MCP to … (replace … with what you need)

Being explicit increases the chance the tool is chosen.

② Recommended Setting (Agent Rules)

Add a rule in agents.md or .cursor so that “phennec” usage in prompts is ensured to trigger MCP tools instead of workspace search.