Skip to main content
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.
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.

​
Verifying Your Authentication

The fastest way to check whether you’re authenticated and connected to the right workspace is to call connect: 
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).
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.

​
Token Storage

LocationContents
~/.hyper/tokenYour Hyper API token, written after first successful OAuth sign-in
~/.hyper/join_tokenA 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.
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.

​
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: 
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.
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.

​
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. 
# Local dev server URL
http://localhost:8000/mcp