@hydra-help/mcp

The official Model Context Protocol stdio bridge for Hydra — the AI-native CRM and support platform.

Connects Claude Desktop, Claude Code, and any other local-only MCP client to your Hydra workspace. Reads, writes, and manages CRM records, conversations, tickets, knowledge, flows, and admin objects, all scope-gated by your tenant API key.

Internally, this package is a small (~70-line, zero-runtime-dependency) bridge: stdin → POST to Hydra's hosted Streamable HTTP MCP endpoint (https://mcp.hydra-help.com/mcp) with your API key as a bearer token → stdout. The 57-tool surface and all data access live on the hosted server — this binary is just the local pipe.

Setup

1. Mint an API key

Sign in to your Hydra workspace and visit /team/api-keys. Create a new key, pick the scopes you want (read-only is a safe default), and copy the hmcp_... token. The token is shown once — store it somewhere safe.

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"
      }
    }
  }
}

Restart Claude Desktop. You should see Hydra's tools appear in the tool picker.

3. (Optional) Pin to a different endpoint

If you're running a self-hosted or staging Hydra MCP, set HYDRA_MCP_URL:

"env": {
  "HYDRA_API_KEY": "hmcp_your_key_here",
  "HYDRA_MCP_URL": "https://your-hydra-mcp.example.com/mcp"
}

Tool surface

The hosted server exposes 57 tools across CRM, conversations, tickets, knowledge, flows, reports, and admin domains. The full list is returned by the standard MCP tools/list call — Claude Desktop and Claude Code surface them automatically once connected.

Every write tool returns a preview first; the actual change only fires when Claude calls the same tool again with the preview's nonce. This is the in-protocol mitigation against prompt-injection-via-tool-result — model-initiated writes never auto-execute.

Scopes

Scopes are bounded by the role of the admin who minted the key:

• Owner / Admin — can mint keys with any scope, including admin:*.
• Member — can mint keys with read scopes plus crm:write, conversations:write, tickets:write, flows:trigger.

Keep keys narrowly-scoped — least-privilege is always available. Revocation is a one-click action on /team/api-keys.

Troubleshooting

HYDRA_API_KEY env var is required — Set the env var inside Claude Desktop's MCP config, not in your shell. Claude Desktop spawns the process with its own env; your shell's env doesn't propagate.

401 Unauthorized on every tool call — The key has been revoked or expired. Mint a fresh one at /team/api-keys.

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

Tools missing or stale — the tool list comes from the hosted server, not this package. New tools land automatically after a Hydra deploy; you don't need to update this package.

Links

• Hydra
• API Keys (mint, revoke, view scopes)
• Source repository
• MCP specification

License

MIT