Connect your AI assistant

Give Claude, Cursor, VS Code, Codex or Gemini read access to your Hook data, so you can ask about phishing results, training and billing in plain language.

Hook has an MCP server: a standard way for AI assistants to read data from other tools. Once it's connected, you can ask your assistant things like "Which of my clients had the highest click rate last month?" or "Who is overdue on training?" and it answers from your Hook data.

The assistant can only read. It can't change anything in Hook, and it only sees the organizations your API key covers.

Setup takes about two minutes.

Before you start

You need an API key. API keys are available to organizations on the new Hook platform. An admin creates one at app.hooksecurity.co/settings/api-keys, which opens the right page for your account. An MSP key covers the MSP and every client under it. An organization key covers only that organization. The key starts with hook_live_ and is shown once, so keep the window open until you've used it.

Never paste your key into a chat

Paste it only into the setup command or settings below. An assistant on your computer saves it there; a Claude chat connector keeps it in your Claude account. Either way, you never need to give it to the assistant in a conversation.

Add Hook to your assistant

Pick your assistant. Wherever you see YOUR_KEY, replace it with your key.

Use this if you work in Claude Code, including the Code tab of the Claude desktop app. Run it once in your terminal. It asks for your key without showing it, so the key never lands in your terminal's history.

On a Mac or Linux (Terminal):

printf 'Paste your Hook key: '; read -rs HOOK_KEY; echo
claude mcp add --scope user --transport http hook https://api.hooksecurity.co/mcp --header "Authorization: Bearer $HOOK_KEY"; unset HOOK_KEY

On Windows (PowerShell):

$HookKey = Read-Host "Paste your Hook key" -AsSecureString
claude mcp add --scope user --transport http hook https://api.hooksecurity.co/mcp --header "Authorization: Bearer $([Net.NetworkCredential]::new('', $HookKey).Password)"; Remove-Variable HookKey

That's it. Claude Code saves it for good: it keeps working after restarts, in every folder, and in the Claude desktop app. Sessions that were already open won't see it, so start a new one.

To check, run this. It should show ✔ Connected.

claude mcp get hook

Install Hook in VS Code

VS Code asks for your key once, in a password box, and stores it securely. Nothing to edit.

Hook works in VS Code's local agent sessions. Copilot cloud sessions don't get servers that ask for a key, so use a local session to reach Hook.

Open Cursor Settings › MCP › Add new MCP server (or the file ~/.cursor/mcp.json) and add:

{
  "mcpServers": {
    "hook": {
      "url": "https://api.hooksecurity.co/mcp",
      "headers": { "Authorization": "Bearer YOUR_KEY" }
    }
  }
}

Works for the Codex CLI, the Codex IDE extension and the ChatGPT desktop app, which share one file. Add this to ~/.codex/config.toml:

[mcp_servers.hook]
url = "https://api.hooksecurity.co/mcp"
http_headers = { "Authorization" = "Bearer YOUR_KEY" }

Only for regular chat conversations

Connectors added here don't reach Claude Code or the desktop app's Code tab. If you work there, use the Claude (desktop app or Code) tab instead.

At claude.ai or in the desktop app's chat, open Settings › Connectors › Add custom connector:

Name:
```
Hook
```
URL:
```
https://api.hooksecurity.co/mcp
```
Authentication: No sign-in.
Under Request headers, add the name
```
authorization
```
with the value below, replacing YOUR_KEY after you paste it:
```
Bearer YOUR_KEY
```

Request headers are in beta

If you don't see Request headers, your plan doesn't have them yet, and chat can't connect to Hook for now. A Sign in with Hook option, with no key to copy, is on the way.

Add this to ~/.gemini/settings.json:

{
  "mcpServers": {
    "hook": {
      "httpUrl": "https://api.hooksecurity.co/mcp",
      "headers": { "Authorization": "Bearer YOUR_KEY" }
    }
  }
}

Any assistant that supports remote MCP servers over HTTP can connect with this URL:

https://api.hooksecurity.co/mcp

and this header:

Authorization: Bearer YOUR_KEY

ChatGPT on the web can't send a key yet; it will work once Sign in with Hook is available.

Check it works

Start a new conversation and ask:

Use the Hook tools: who am I, and which organizations can I see?

The assistant asks permission the first time it uses a Hook tool. It should answer with the number of organizations your key covers and list them.

What you can ask about

Organizations your key covers, with their active user counts.
Phishing campaigns, their results, and each person's outcome.
Training enrollments, including who is overdue.
Billable users per month for accounts on the new Hook platform. An account created there bills its peak day. An account that moved there bills the people in Hook's records that month who aren't set inactive today. Both start in October 2026. The API docs have the details.

Campaign and training numbers match Hook's own reports for the same organization and period.

Troubleshooting

Hook doesn't show up. Start a new session or reopen the app; open sessions don't pick up new servers. In Claude Code, make sure the command included --scope user.

Your assistant says it has no Hook tools. Hook was added somewhere this session doesn't read. Check that you added it in the same app and profile you're using, then start a new session. In Claude, Code sessions (including the desktop app's Code tab) only use servers added with the Claude Code command; chat connectors don't count.

"Failed to connect" or "401 Unauthorized". The key is wrong or was replaced. Remove Hook from your assistant and add it again with the right key, using its tab above. In Claude Code, remove it first with:

claude mcp remove hook --scope user

An organization is missing. A key covers its own organization, or for an MSP key, the MSP and its clients. Ask an admin for a key at the right level.

Keep your data safe

Each person should have their own key, so one can be revoked without affecting anyone else. Revoke a key in Settings › API keys.
Names of organizations, campaigns and people come from your data. Your assistant treats them as data, but review what it does before approving actions in other tools.