Hydra DB — MCP Server

MCP (Model Context Protocol) server for Hydra DB, the state-of-the-art agentic memory. Provides tools for storing, recalling, and managing memories with knowledge-graph enriched context.

Available Tools

The tool names follow the canonical HydraDB vocabulary. Every previous name still works as a deprecated alias (marked as such in its description) so existing mcp.json files keep working — but new integrations should use the canonical names below.

hydradb_query

Search through Hydra DB memories. Returns relevant chunks with graph-enriched context including entity paths and knowledge graph relations.

hydradb_ingest

Save information to Hydra DB memory. Hydra DB automatically extracts insights, preferences, and builds a knowledge graph from the stored content. Provide text to store a note/document, or turns to ingest a conversation.

* Provide exactly one of text or turns.

hydradb_list

List stored memories or ingested knowledge sources in Hydra DB.

hydradb_inspect

Fetch the full content of a specific source by its source ID.

hydradb_delete

Delete a memory or knowledge source from Hydra DB by its ID. This action is irreversible.

Related MCP server: MCP-Mem0

Configuration

Get Your Credentials

1. Get your Hydra DB API Key from Hydra DB

2. Get your database name from the Hydra DB dashboard

Environment Variables

The legacy HYDRA_DB_* names — HYDRA_DB_API_KEY, HYDRA_DB_TENANT_ID, HYDRA_DB_SUB_TENANT_ID, HYDRA_DB_BASE_URL, HYDRA_DB_LOG_LEVEL — remain honoured as deprecated aliases (canonical wins when both are set; using an alias prints a one-time warning naming its replacement).

Claude Desktop

{
  "mcpServers": {
    "hydradb": {
      "command": "npx",
      "args": ["-y", "@hydradb/mcp@latest"],
      "env": {
        "HYDRADB_API_KEY": "your-api-key",
        "HYDRADB_DATABASE": "your-database"
      }
    }
  }
}

Cursor & Windsurf

{
  "mcpServers": {
    "hydradb": {
      "command": "npx",
      "args": ["-y", "@hydradb/mcp@latest"],
      "env": {
        "HYDRADB_API_KEY": "your-api-key",
        "HYDRADB_DATABASE": "your-database"
      }
    }
  }
}

VS Code

Add to .vscode/mcp.json:

{
  "servers": {
    "hydradb": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@hydradb/mcp@latest"],
      "env": {
        "HYDRADB_API_KEY": "your-api-key",
        "HYDRADB_DATABASE": "your-database"
      }
    }
  }
}

Custom Sub-Tenant

To partition data, set the HYDRADB_COLLECTION environment variable:

{
  "mcpServers": {
    "hydradb": {
      "command": "npx",
      "args": ["-y", "@hydradb/mcp@latest"],
      "env": {
        "HYDRADB_API_KEY": "your-api-key",
        "HYDRADB_DATABASE": "your-database",
        "HYDRADB_COLLECTION": "my-project"
      }
    }
  }
}

How It Works

The server talks to Hydra DB through the generated @hydradb/sdk (pinned exactly), behind a thin hand-owned wrapper in src/hydra. The wrapper owns scope injection, envelope unwrapping and error translation; the tools call it and render the results.

• hydradb_query retrieves relevant memories and returns graph-enriched context (entity paths, chunk relations, extra context). Supports fast and thinking recall modes.

• hydradb_ingest stores a note (text) or a conversation (turns) as a memory, with configurable infer, is_markdown, title, and source_id. Hydra DB extracts insights and builds a knowledge graph automatically.

• hydradb_list browses stored memories (kind: memory) or ingested knowledge sources (kind: knowledge, with an optional source_ids filter).

• hydradb_inspect retrieves the original ingested content of a source, with mode options (content, url, or both).

• hydradb_delete removes a memory or knowledge source by ID.

Development

npm ci
npm run build
HYDRADB_API_KEY=your-key HYDRADB_DATABASE=your-database npm start

For development with auto-reload:

HYDRADB_API_KEY=your-key HYDRADB_DATABASE=your-database npm run dev

Testing

# unit + conformance tests (wrapper driven against a mocked SDK transport)
npm test

# just the shared conformance vectors
npm run test:conformance

# live integration test against Hydra DB (drives the wrapper end to end)
RUN_LIVE_TESTS=true HYDRADB_API_KEY=your-key HYDRADB_DATABASE=your-database npm run test:integration

Troubleshooting

• API Key Issues: Ensure HYDRADB_API_KEY is set correctly

• Connection Errors: Check your internet connection and API key validity

• Tool Not Found: Make sure the package is installed and the command path is correct

• Debug Logging: Set HYDRADB_LOG_LEVEL=DEBUG for verbose output

Contributing / Developer Setup

Get up and running quickly with the bootstrap script:

git clone https://github.com/usecortex/hydradb-mcp.git
cd hydradb-mcp
make bootstrap

This will install dependencies, build the project, and create a .env file from .env.example. Edit .env with your HydraDB credentials, then:

make dev          # Start MCP server in dev mode (auto-reload)
make test         # Run unit tests
make test-all     # Run unit + integration tests
make check-types  # Type-check without emitting

Run make help to see all available targets.