Onboarding Guide

Two ways onto a team

Either your team admin invites your GitHub username or your email directly, or your team has its github_org set to a GitHub org you belong to — in which case the first time you sign in, GrooveOS auto-adds you. See Authentication for the full org-auto-join rules.

If you got an email invite, you can either click the link inside, or just go straight to grooveos.app/account/teams/ and sign in.

Authenticate via the xbrain GitHub App

GrooveOS signs you in with GitHub — no passwords to manage. Click Sign in with GitHub and authorize the xbrain App. It asks for two read-only permissions: your email addresses (for notifications and admin invites) and your org memberships (for the auto-join rule). Nothing else.

If your GitHub org hasn't installed xbrain yet, GrooveOS shows an "Install xbrain on your-org" banner. An org owner clicks it once; afterwards every member of the org can sign in. See Installing on your org for the consent screen flow.

Confirm you see your team in the dashboard

After signing in you land on the dashboard. In the top-right corner you should see your team name (e.g. acme-corp). This is your team_scope — the namespace that isolates all your team's data.

If you see "No team" or a different team, contact your admin. They may need to add your GitHub username to the team, or set github_org on the team to match one of your orgs.

Create an xbt_ token scoped to your team

Go to Settings → API Tokens in the dashboard and click New token. Give it a descriptive name like claude-mcp or chatgpt-actions.

The token is shown once — copy it immediately and store it in a password manager or secure note. It looks like:

xbt_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2

This token is automatically scoped to your team_scope. Any request made with it can only read or write data belonging to your team — cross-team access is impossible by design.

Add GrooveOS as a remote MCP server in Claude.ai

In Claude.ai, open Settings → Integrations → MCP Servers and click Add server. Fill in:

Name:   GrooveOS Brain
URL:    https://mcp.grooveos.app/mcp
Auth:   Bearer  →  paste your xbt_ token

Save the integration. You should see a green "Connected" badge within a few seconds. Claude.ai will now list the available tools in the tool panel.

Available tools

• memory_search — semantic search across team memory
• memory_add — store a new memory item
• tasks_list — list open tasks for the team
• task_create — create a new task
• task_update — update task status or assignee
• contacts_search — find contacts by name or email
• contact_add — add a new contact
• agent_invoke — run a GrooveOS agent by name
• team_context — fetch recent team context (memories + tasks)

Import the OpenAPI schema into a custom GPT

In ChatGPT, create or edit a Custom GPT and open the Actions tab. Click Import from URL and paste:

https://mcp.grooveos.app/openapi.json

ChatGPT will fetch the schema and populate the action list automatically. Under Authentication, choose API Key → Bearer, and paste your xbt_ token.

Save the GPT. The same 9 tools are available — your custom GPT can now read and write your team's shared brain.

Run a quick end-to-end test

Ask your AI assistant (Claude or ChatGPT) to store a test memory:

Please add this to team memory:
"Onboarding test completed by [your name] on [today's date]."

The assistant should call memory_add and confirm the item was stored. Next, verify the round-trip by searching for it:

Search memory for "onboarding test"

If you get the item back, your integration is working end-to-end. You can now delete the test item with memory_search to find its ID, then remove it from the dashboard under Memory.