> ## 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.

# Connect Hyper to Claude Desktop and Claude Code

> Add the Hyper MCP server to Claude Desktop or Claude Code in minutes and configure lifecycle hooks so memory works automatically across sessions.

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:

```json claude_desktop_config.json theme={null}
{
  "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

<Steps>
  <Step title="Open a new Claude conversation">
    Start a fresh chat in Claude Desktop.
  </Step>

  <Step title="Ask Claude to connect">
    Type the following message and send it:

    ```text theme={null}
    Please call the Hyper connect tool.
    ```
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Note>
  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).
</Note>

***

## 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.

<CardGroup cols={2}>
  <Card title="SessionStart" icon="play" href="/guides/claude-setup#hooks-for-claude-desktop">
    Runs `hyper connect` when a session begins, loading your identity and workspace context into Claude's context window.
  </Card>

  <Card title="UserPromptSubmit" icon="message" href="/guides/claude-setup#hooks-for-claude-desktop">
    Runs `hyper ask` with each message you send, retrieving memories relevant to your current question.
  </Card>

  <Card title="Stop" icon="square" href="/guides/claude-setup#hooks-for-claude-desktop">
    Runs `hyper remember` when a session ends, evaluating the conversation and persisting anything worth saving.
  </Card>

  <Card title="Always-on" icon="rotate" href="/guides/claude-setup#hooks-for-claude-code">
    Once configured, hooks fire silently in the background — no extra prompts, no manual steps.
  </Card>
</CardGroup>

### 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):

```json hooks.json theme={null}
{
  "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:

```json .claude/settings.json theme={null}
{
  "hooks": {
    "SessionStart": {
      "command": "hyper connect"
    },
    "UserPromptSubmit": {
      "command": "hyper ask",
      "passUserMessage": true
    },
    "Stop": {
      "command": "hyper remember"
    }
  }
}
```

<Tip>
  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.
</Tip>

***

## Troubleshooting

<Warning>
  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.
</Warning>

| Symptom                                      | Fix                                                                                    |
| -------------------------------------------- | -------------------------------------------------------------------------------------- |
| Claude says it can't find the `connect` tool | Verify `claude_desktop_config.json` is valid JSON and restart Claude Desktop           |
| OAuth window appears but loops               | Delete `~/.hyper/token` and try again                                                  |
| Hooks don't fire                             | Confirm the hooks file is saved in the correct directory and has no JSON syntax errors |
| Context seems stale                          | Call `connect` manually to force a fresh workspace load                                |

***

## Local Development

If you're running a local Hyper instance, swap the server URL to:

```json theme={null}
{
  "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.