MCP Setup

The HydraCore MCP server exposes the full tenant API as MCP tools. Point any MCP-capable client at it with an API key and you can list instances, deploy agents, manage credentials, query usage, and more from inside the assistant.

This page covers three clients — Claude Desktop, Cursor, and Goose. The MCP server itself is identical across them; only the client config file changes.

Prerequisites

• Python 3.11 or newer on the machine that runs your MCP client.
• A HydraCore tenant API key with the scopes you intend to use. The MCP server fetches your key's scopes at startup and filters the tool list accordingly — a key with only instances:read will not surface create_instance / delete_instance tools at all.

Mint an API key

1. Sign in at platform.hydracore.io.
2. Open Settings → API Keys → New key.
3. Pick scopes. Scopes follow <resource>:<verb> shape — see the API Reference for the full list. For a "drive my whole tenant" key you want every *:read, *:write, plus instances:delete and mcp-creds:read / mcp-creds:write.
4. Copy the hc_live_… value — it is shown once and never again.

API keys are tenant-scoped. They do not carry user-level admin privileges; ops endpoints (/internal/v1/…) are unreachable from any API key regardless of scope.

Install the MCP server

The MCP server is a Python package shipped from this repo. There is no PyPI release yet, so install directly from the repo with pipx (isolated venv, single executable on $PATH):

pipx install git+https://github.com/battman21/hydracore.git#subdirectory=platform/mcp-server

A PyPI release is on the roadmap; once it lands the install command becomes pipx install hydracore-mcp-server.

You should now have hydracore-mcp-server on your path. Verify with:

HYDRACORE_API_URL=https://api.hydracore.io \
HYDRACORE_API_KEY=hc_live_... \
hydracore-mcp-server --help

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json on macOS (or %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "hydracore": {
      "command": "hydracore-mcp-server",
      "env": {
        "HYDRACORE_API_URL": "https://api.hydracore.io",
        "HYDRACORE_API_KEY": "hc_live_..."
      }
    }
  }
}

Restart Claude Desktop. The hammer icon in the chat input should show hydracore with a tool count that matches your API key's scope set.

Cursor

Cursor reads ~/.cursor/mcp.json (global) or .cursor/mcp.json in the workspace root (per-project):

{
  "mcpServers": {
    "hydracore": {
      "command": "hydracore-mcp-server",
      "env": {
        "HYDRACORE_API_URL": "https://api.hydracore.io",
        "HYDRACORE_API_KEY": "hc_live_..."
      }
    }
  }
}

Reload the Cursor window. The Composer's tool picker lists the HydraCore tools alongside any other MCP servers you have configured.

Goose

Goose configures MCP servers in ~/.config/goose/config.yaml. Add the extensions block:

extensions:
  hydracore:
    type: stdio
    cmd: hydracore-mcp-server
    envs:
      HYDRACORE_API_URL: https://api.hydracore.io
      HYDRACORE_API_KEY: hc_live_...

Restart goose or run goose configure to pick up the change. The extension shows up in goose info's extension list once loaded.

Auth model

The server prefers HYDRACORE_API_KEY over the legacy HYDRACORE_TOKEN JWT fallback. API-key auth is the supported path:

• Scope filtering. At startup the server calls GET /v1/mcp/api-key-context. The response carries the key's scopes; the server uses them to filter list_tools() so a tool the key cannot call is never even shown to the model.
• Audit log. Every tool call best-effort posts an audit row to /v1/mcp/audit-log so the tenant has a record of what the assistant did on its behalf. A failed audit post never breaks a tool call.

The JWT fallback exists for transition compatibility only; it disables scope filtering (every tool visible). Migrate to API keys when you can.

Troubleshooting

• No tools appear. The server failed to fetch /v1/mcp/api-key-context. Check the client's stderr stream (Claude Desktop: ~/Library/Logs/Claude/mcp-server-hydracore.log) for the underlying HTTP error. Usual cause: wrong HYDRACORE_API_URL or revoked key.
• Tool calls 403. Your API key is missing the scope that gates the endpoint. Mint a new key with the right scope set; rotation is free.
• Tool calls 401 but key is fresh. The key was minted for a different tenant than the one whose data the tool tries to read. API keys are tenant-scoped; check Settings → API Keys to confirm the key's tenant_id.