> ## Documentation Index
> Fetch the complete documentation index at: https://hmm.heyhyper.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Hyper MCP: Authentication with OAuth 2.0 and Tokens

> Hyper uses OAuth 2.0 with Google sign-in. Learn how tokens are stored, rotated, and how to join multiple workspaces with a join token.

Hyper authenticates over OAuth 2.0 using your Google account. When you point an MCP-compatible client at the Hyper server URL for the first time, it initiates the OAuth flow automatically — you sign in with Google, grant access, and the client receives a Hyper API token that it stores locally. Every subsequent connection reuses that token silently, so you only go through sign-in once.

## How the OAuth Flow Works

The flow is entirely driven by your MCP client — you don't need to manage tokens or credentials manually.

1. Add `https://hyperlink.gethyper.space/mcp` as an MCP server in your client.
2. Your client detects that authentication is required and opens the OAuth prompt.
3. Sign in with Google — use the same Google account associated with your Hyper workspace.
4. After a successful sign-in, Hyper issues an API token and your client stores it at `~/.hyper/token`.
5. All future MCP connections read from that file automatically.

<Note>
  The token stored at `~/.hyper/token` is a **Hyper API token**, not a raw OAuth token. Hyper exchanges your OAuth grant for its own session token behind the scenes, so the file contains a Hyper-specific credential rather than a Google access token.
</Note>

## Verifying Your Authentication

The fastest way to check whether you're authenticated and connected to the right workspace is to call `connect`:

```python theme={null}
connect()
```

If you get back a briefing block — with your name, workspace, and recent activity — you're fully authenticated. If the response returns `action: not_set_up`, open the Hyper desktop app to complete onboarding first. If it returns `action: no_workspace`, you may need to join a workspace (see below).

<Tip>
  Lifecycle hooks handle this for you automatically. If you've configured the `SessionStart` hook to call `connect`, authentication is verified at the start of every conversation without any manual step.
</Tip>

## Token Storage

| Location              | Contents                                                           |
| --------------------- | ------------------------------------------------------------------ |
| `~/.hyper/token`      | Your Hyper API token, written after first successful OAuth sign-in |
| `~/.hyper/join_token` | A workspace join token, if one was placed there by your team admin |

Both files are read by the MCP server automatically. You don't need to reference them directly in normal usage.

## Token Rotation

Hyper API tokens do **not** expire on a fixed schedule. Your token remains valid until you explicitly revoke it or re-authenticate. If your token stops working — for example, after a security rotation or account change — re-authenticate through the Hyper desktop app:

1. Open the Hyper desktop app.
2. Navigate to **Settings → Account**.
3. Click **Re-authenticate** to go through the OAuth flow again.
4. The desktop app overwrites `~/.hyper/token` with the new token automatically.

<Warning>
  If you delete `~/.hyper/token` manually, your next `connect` call will trigger the full OAuth flow again. Make sure your MCP client is ready to handle the browser redirect before doing this.
</Warning>

## Joining Multiple Workspaces

Each Hyper token is scoped to a single workspace by default. To join an additional workspace — for example, if you're a contractor working across two organizations — pass a `join_token` to the `connect` tool:

```python theme={null}
connect(join_token="tk_abc123xyz")
```

Your team admin can generate a join token from the Hyper desktop app or web dashboard and share it with you directly. Alternatively, if your admin has placed a join token at `~/.hyper/join_token`, the `connect` tool will pick it up automatically without you needing to pass it explicitly.

<Note>
  After joining a new workspace, subsequent `connect` calls will load that workspace's briefing. To switch back to a different workspace, call `connect` again with that workspace's join token.
</Note>

## Local Development

If you're running a local Hyper server, use `http://localhost:8000/mcp` as your MCP server URL. Authentication works identically — the same `~/.hyper/token` file is used, and the OAuth flow is initiated by your client if the token is missing or invalid.

```text theme={null}
# Local dev server URL
http://localhost:8000/mcp
```