Skip to main content
Hyper plugs into Claude through the Model Context Protocol (MCP), giving Claude persistent memory across every conversation. Once connected, Claude can recall past decisions, load your workspace identity, and save anything worth remembering — without you lifting a finger. This guide walks you through setup for both Claude Desktop and Claude Code.

​
Claude Desktop

​
Add the MCP Server

Open your claude_desktop_config.json file. You can find it at:
  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\\Claude\\claude_desktop_config.json
Add the Hyper server under the mcpServers key:
claude_desktop_config.json
{
  "mcpServers": {
    "hyper": {
      "url": "https://hyperlink.gethyper.space/mcp"
    }
  }
}
Save the file, then quit and relaunch Claude Desktop so it picks up the new configuration.

​
Authenticate

The first time Claude calls any Hyper tool, the MCP server will redirect you through an OAuth 2.0 flow. A browser window opens and prompts you to sign in with Google. After you approve, your bearer token is saved to ~/.hyper/token and all future requests are authenticated automatically.

​
Verify the Connection

1

Open a new Claude conversation

Start a fresh chat in Claude Desktop.
2

Ask Claude to connect

Type the following message and send it:
Please call the Hyper connect tool.
3

Check the briefing

Claude should respond with a workspace briefing — your identity, active workspace, and any pinned context. If you see this, Hyper is working correctly.
If Claude doesn’t find the connect tool, confirm that claude_desktop_config.json is valid JSON and that you fully restarted Claude Desktop (not just closed the window).

​
Configure Automatic Memory with Hooks

Without hooks, you need to manually ask Claude to remember things. With hooks, Hyper’s three lifecycle events fire automatically on every session.

SessionStart

Runs hyper connect when a session begins, loading your identity and workspace context into Claude’s context window.

UserPromptSubmit

Runs hyper ask with each message you send, retrieving memories relevant to your current question.

Stop

Runs hyper remember when a session ends, evaluating the conversation and persisting anything worth saving.

Always-on

Once configured, hooks fire silently in the background — no extra prompts, no manual steps.

​
Hooks for Claude Desktop

Add a hooks.json file alongside your claude_desktop_config.json. The exact path depends on your OS (same directory as the config file above):
hooks.json
{
  "hooks": {
    "SessionStart": {
      "command": "hyper connect"
    },
    "UserPromptSubmit": {
      "command": "hyper ask",
      "passUserMessage": true
    },
    "Stop": {
      "command": "hyper remember"
    }
  }
}

​
Hooks for Claude Code

Claude Code reads hooks from .claude/settings.json in your project root (or your home directory for global settings). Add the hooks key to that file:
.claude/settings.json
{
  "hooks": {
    "SessionStart": {
      "command": "hyper connect"
    },
    "UserPromptSubmit": {
      "command": "hyper ask",
      "passUserMessage": true
    },
    "Stop": {
      "command": "hyper remember"
    }
  }
}
For a global Claude Code setup that applies to every project, place settings.json in ~/.claude/settings.json rather than inside an individual project directory.

​
Troubleshooting

If the OAuth window never appears, check that your system’s default browser is configured and that https://hyperlink.gethyper.space is reachable from your network. Corporate VPNs or firewalls can sometimes block the redirect.
SymptomFix
Claude says it can’t find the connect toolVerify claude_desktop_config.json is valid JSON and restart Claude Desktop
OAuth window appears but loopsDelete ~/.hyper/token and try again
Hooks don’t fireConfirm the hooks file is saved in the correct directory and has no JSON syntax errors
Context seems staleCall connect manually to force a fresh workspace load

​
Local Development

If you’re running a local Hyper instance, swap the server URL to: 
{
  "mcpServers": {
    "hyper": {
      "url": "http://localhost:8000/mcp"
    }
  }
}
Keep the production URL in your main config and use a separate profile or config file for local dev to avoid accidentally mixing environments.