Connect Claude Desktop

Hydra ships an official Model Context Protocol (MCP) server that lets Claude Desktop, Claude Code, Cursor, and any other MCP-compatible AI client read and write your Hydra workspace — CRM records, conversations, tickets, knowledge, flows, reports, and (with admin scopes) team and channel management.

The full 57-tool surface is hosted at https://mcp.hydra-help.com and accessed through the npm package @hydra-help/mcp.

Quick start

1. Mint an API key

Go to Settings → API Access and click New API key. Give it a name (e.g. "Claude Desktop"), pick scopes (read-only is a safe default — crm:read, conversations:read, tickets:read, knowledge:read, reports:read), and click Create key.

The key is shown once — copy it (looks like hmcp_...) somewhere safe before closing the modal.

For more on key management, see API Keys.

2. Add Hydra to Claude Desktop

Open Claude Desktop's MCP config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add a hydra entry under mcpServers:

{
  "mcpServers": {
    "hydra": {
      "command": "npx",
      "args": ["-y", "@hydra-help/mcp"],
      "env": {
        "HYDRA_API_KEY": "hmcp_your_key_here"
      }
    }
  }
}

Save the file and restart Claude Desktop.

3. Try it

Once Claude Desktop reconnects, you should see Hydra's tools appear in the tool picker. Try asking Claude things like:

• "List my newest leads."
• "Show me open tickets assigned to me."
• "Summarize the most recent conversation in the support channel."
• "Search the knowledge base for refund policy."

For write actions ("Create a new lead named …", "Close that ticket"), Claude will show you a preview first — a list of exactly what will change — and only execute when you confirm. This applies to every write tool by design; model-initiated writes never auto-execute.

What scopes do I need?

Match the scopes on your key to what you want Claude to be able to do:

Members can mint keys with the read/write scopes only. admin:* scopes require Owner or Admin role on the workspace.

Use other MCP clients

The same npm package works in any MCP-compatible client that supports stdio transport. Replace command: "npx" and args: ["-y", "@hydra-help/mcp"] in the client's config — the env-var setup (HYDRA_API_KEY) is identical.

If your client supports remote MCP servers directly (Streamable HTTP), point it at https://mcp.hydra-help.com/mcp with Authorization: Bearer hmcp_... and skip the local bridge entirely.

Troubleshooting

HYDRA_API_KEY env var is required Set the env var inside Claude Desktop's MCP config under "env", not in your shell. Claude Desktop spawns the bridge with its own environment; your shell's variables don't propagate.

Tools don't appear in Claude Desktop Confirm Claude Desktop fully restarted after editing the config. Check Claude Desktop's developer console (View → Developer → Show Logs) for any startup errors.

401 Unauthorized on every tool call The API key has been revoked or expired. Mint a fresh one from Settings → API Access.

403 Forbidden: missing scope X The key doesn't have the scope required for that specific tool. The error names the missing scope — either mint a new key with that scope checked, or use a higher-privileged key.

Tools appear stale or missing Tool definitions live on the hosted server, not in the npm package. New tools land automatically the next time Claude Desktop reconnects — no npm update needed.

Security notes

• Keys are tenant-scoped — a key from your workspace can't read another workspace's data.
• Every MCP call is logged in your audit log (Settings → Audit Log) with key prefix, tool name, and timestamp.
• Revoke any key instantly from Settings → API Access.
• The npm package itself stores no credentials — the API key is read from the env var Claude Desktop passes in at spawn.

Links

• API Keys — minting, scopes, monthly caps, revoking
• Audit Log — review what every key has done
• Source code — the bridge is open source (~70 lines, zero runtime deps)
• Model Context Protocol — the underlying spec