HydraDB MCP

Quick Start

The fastest way in is Sign in with HydraDB: paste one URL into your AI app, approve it in the browser, done. No API key, no config file to edit.

Sign in with HydraDB (recommended)
API key

Here is how you can connect:

claude mcp add --transport http hydradb https://mcp.hydradb.com

Then run /mcp, choose hydradb, and click Authenticate.

Settings → Connectors → Add custom connector, paste https://mcp.hydradb.com, then click Connect.

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "hydradb": { "url": "https://mcp.hydradb.com" }
  }
}

Restart Cursor, then click Connect on the server in Settings → MCP.

Add to .vscode/mcp.json:

{
  "servers": {
    "hydradb": { "type": "http", "url": "https://mcp.hydradb.com" }
  }
}

opencode mcp add hydradb --url https://mcp.hydradb.com
opencode mcp auth hydradb

codex mcp add hydradb --url https://mcp.hydradb.com
codex mcp login hydradb

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "hydradb": { "serverUrl": "https://mcp.hydradb.com" }
  }
}

Not sure where to put the URL? Paste this to your AI assistant and it will add or update the config file for you:

Add the HydraDB MCP server at https://mcp.hydradb.com to my MCP config, then help me authenticate.

What you are approving

The approval screen shows the app asking to connect, what it will be able to do, and which database it will read and write. It also asks whether the app may use your other databases:

Allowed when asked (default) - the app starts in the database you picked and can switch to another one of yours when you tell it to. Choose this if you work across several databases.
Not allowed - the app is confined to that database, and to the collection shown under Advanced (hydra-db-mcp unless you change it). Anything else is refused, including a request to delete a graph in another collection.

You can change your mind at any time: Settings → Connected apps lists every app you have connected and Disconnect cuts one off immediately.

Signing in is preferred, but an API key still works everywhere and is the right choice for servers, CI, scripts, and self-hosted deployments where no browser is available.

Get your credentials

Create an API key from the HydraDB dashboard
Create or copy your database ID from the HydraDB dashboard

Connect your client

Remote MCP server
Local MCP server

Point your client at https://mcp.hydradb.com and pass your credentials as headers. The key names differ by client: VS Code uses the servers schema with an explicit type, the others use mcpServers. See authentication for every header.

Claude Desktop / Cursor / Windsurf
VS Code

{
  "mcpServers": {
    "hydradb": {
      "url": "https://mcp.hydradb.com",
      "headers": {
        "Authorization": "Bearer YOUR_HYDRADB_API_KEY",
        "X-HydraDB-Database": "your-database"
      }
    }
  }
}

Add to .vscode/mcp.json - note the servers key and the explicit "type": "http":

{
  "servers": {
    "hydradb": {
      "type": "http",
      "url": "https://mcp.hydradb.com",
      "headers": {
        "Authorization": "Bearer YOUR_HYDRADB_API_KEY",
        "X-HydraDB-Database": "your-database"
      }
    }
  }
}

Your client spawns the server over stdio. Requires Node.js 18 or later (node --version to check).

Claude Desktop
Cursor
Windsurf
VS Code

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

Add to ~/.cursor/mcp.json:

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

Add to ~/.codeium/windsurf/mcp_config.json:

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

Add to .vscode/mcp.json:

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

Replace the placeholders and restart

Swap YOUR_HYDRADB_API_KEY / your-api-key and your-database for the values from Step 1, then restart your editor or client so it picks up the new MCP server.

Local MCP server only: the canonical tool names and HYDRADB_* variables need @hydradb/mcp 1.1.0 or later. If your config pins @0.0.1 or @1.0.0, change it to @^1.1.0 and restart. Nothing else changes - every name you were using before still works, and the caret keeps you on the 1.x line this page documents.

Authenticating to the remote server

There are two ways to authenticate against https://mcp.hydradb.com, and the same URL serves both. Point your client at the URL with no credentials and it discovers the sign-in flow on its own: the server answers 401 with a pointer to its metadata, your client registers itself, and opens your browser. You sign in, choose a database, and approve. Your client stores a token that it refreshes silently, and you never handle a key. Disconnect any app from Settings → Connected apps. That revokes its access immediately.

API key headers

Every request carries its own credentials, so one server serves any number of independent users. Send them as headers:

Header	Maps to	Required
`Authorization`	Your HydraDB API key as a `Bearer` token (`X-HydraDB-Api-Key` is also accepted), or an OAuth access token	Yes
`X-HydraDB-Database`	Database (tenant scope). API-key requests only; ignored for an OAuth token, whose scope comes from what you approved	Yes*
`X-HydraDB-Collection`	Collection (sub-tenant); defaults to `hydra-db-mcp`	No
`X-HydraDB-Graph-Database`	Default graph database for the Cypher tools; defaults to the request’s database	No
`X-HydraDB-Graph-Collection`	Default graph collection; defaults to `default`	No

* Required with an API key. Not needed, and not read, with an OAuth token. A request that authenticates nobody is refused with 401, and that refusal is what starts the sign-in flow for clients that support it. A request that carries an API key but names no database is refused with 400; an OAuth token needs no database header, because the database was chosen when you approved the app.

The API key and database resolve together: a request that supplies its own key must also supply its own X-HydraDB-Database, so your key is never paired with another tenant’s data. The base URL, request timeout, and retry count are operator settings on the server and are never read from a request header.

Per-call tenant switching: Multi-tenant agents serving multiple companies from a single session can pass database and collection directly in tool arguments (e.g. hydradb_query with {"query": "...", "database": "tenant_b"}). When omitted, calls fall back to the connection’s default scope: the X-HydraDB-Database / X-HydraDB-Collection headers for an API key, or what you approved for an OAuth connection.On an OAuth connection you approved with other databases not allowed, a per-call database or collection outside that scope is refused before the request leaves the server, and hydradb_databases shows what the connection may use.

Self-hosting the HTTP server

Prefer to run the remote server yourself instead of using mcp.hydradb.com? Use the npm binary or the Docker image. Set HYDRADB_API_KEY and HYDRADB_DATABASE in the environment for a single-tenant server (clients then send no credentials), or leave them unset for a multi-tenant one where every client authenticates with its own headers.

npm
Docker

npm install -g @hydradb/mcp
# Single-tenant: the server holds one account
HYDRADB_API_KEY=your-key HYDRADB_DATABASE=your-database hydradb-mcp-http
# Multi-tenant: clients authenticate per request
BIND_ADDRESS=0.0.0.0 ALLOWED_HOSTS=mcp.hydradb.com hydradb-mcp-http

docker build -t hydradb-mcp https://github.com/hydra-db/hydradb-mcp.git
docker run -p 8080:8080 \
  -e HYDRADB_API_KEY=your-key -e HYDRADB_DATABASE=your-database \
  hydradb-mcp

The primary endpoint is POST / (with /mcp supported as an alias); GET /health is an unauthenticated liveness probe.

Variable	Description	Default
`PORT`	Port to listen on	`8080`
`BIND_ADDRESS`	Interface to bind (`0.0.0.0` to accept off-host)	`127.0.0.1`
`ALLOWED_HOSTS`	Extra `Host` headers to accept (comma-separated); loopback always allowed	(loopback only)
`ALLOWED_ORIGINS`	CORS origins for browser clients (comma-separated; `*` allows any)	(none)
`TRUST_PROXY`	Express `trust proxy` when behind a reverse proxy: a hop count, `true`, or `loopback`	off

The defaults are loopback-only. When you expose the server publicly, bind 0.0.0.0 deliberately, set ALLOWED_HOSTS to your hostname, list any browser origins in ALLOWED_ORIGINS, and terminate TLS in front of it. For a shared, public server, leave HYDRADB_API_KEY unset so every caller must authenticate with their own key rather than sharing yours.

Configuration

Environment Variables

Variable	Description	Default
`HYDRADB_API_KEY`	Your HydraDB API key	Required
`HYDRADB_DATABASE`	The database to read and write	Required
`HYDRADB_COLLECTION`	Collection to partition data within the database	`hydra-db-mcp`
`HYDRADB_BASE_URL`	API base URL override	`https://api.hydradb.com`
`HYDRADB_LOG_LEVEL`	Log level: `DEBUG`, `INFO`, `WARN`, `ERROR`	`ERROR`

Deprecated variable names

The HYDRA_DB_* spellings still work. Each one is read as a deprecated alias of its canonical name and prints a single warning to stderr naming the replacement; if both are set, the canonical name wins.

Deprecated	Canonical
`HYDRA_DB_API_KEY`	`HYDRADB_API_KEY`
`HYDRA_DB_TENANT_ID`	`HYDRADB_DATABASE`
`HYDRA_DB_SUB_TENANT_ID`	`HYDRADB_COLLECTION`
`HYDRA_DB_BASE_URL`	`HYDRADB_BASE_URL`
`HYDRA_DB_LOG_LEVEL`	`HYDRADB_LOG_LEVEL`

See the Glossary for why tenant became database.

Collections

Use HYDRADB_COLLECTION to partition data across projects within one database:

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

Give each project its own HYDRADB_COLLECTION to keep memory isolated, or point several projects at the same value to share context between them. Unset, the server writes to and reads from hydra-db-mcp.

Available Tools

Tool names follow the canonical HydraDB vocabulary - one verb per action, with the same scope names the rest of the product uses. See the Glossary.

Tool	What it does
`hydradb_query`	Search memories; returns matching chunks plus graph-enriched context - entity paths, chunk relations, extra context
`hydradb_ingest`	Store a note (`text`) or a conversation (`turns`); HydraDB extracts insights and builds the knowledge graph
`hydradb_list`	Browse stored memories or ingested knowledge sources
`hydradb_inspect`	Retrieve the original content of a source by ID
`hydradb_delete`	Remove a memory or knowledge source by ID
`hydradb_databases`	List the databases this connection can use, with the default marked. Available on OAuth connections

hydradb_query

Parameter	Type	Required	Description
`query`	string	Yes	The search query to find relevant memories
`kind`	string	No	Which family to search: `memory`, `knowledge`, or `all` (default: `all`)
`max_results`	number	No	Chunks to return, 1-50 (default: `10`)
`mode`	string	No	`fast` for quick semantic search, `thinking` for deeper personalised recall with graph traversal (default: `thinking`)
`graph_context`	boolean	No	Include knowledge graph relations in the results (default: `true`)
`metadata_filters`	object	No	Exact-match metadata filters as `{key: value}`
`database`	string	No	Database (tenant) scope override for this request
`collection`	string	No	Collection (sub-tenant) scope override for this request

hydradb_ingest

Provide exactly one of text or turns. Passing both is rejected.

Parameter	Type	Required	Description
`text`	string	No*	The information to store
`turns`	array	No*	Conversation turns to ingest instead of `text`, each with a `user` and an `assistant` field
`kind`	string	No	What to write: `memory` (default) or `knowledge`
`title`	string	No	Title for the entry
`source_id`	string	No	Optional identifier for this entry
`infer`	boolean	No	Let HydraDB extract insights and build the knowledge graph (default: `true`)
`is_markdown`	boolean	No	Treat `text` as markdown (default: `false`)
`metadata`	object	No	Key/value metadata stored with memory, matchable later via `metadata_filters`
`observation_date`	string	No	Calendar date YYYY-MM-DD when the fact was true
`user_name`	string	No	Name of the user, used with `turns` for personalisation (default: `User`)
`database`	string	No	Database (tenant) scope override for this request
`collection`	string	No	Collection (sub-tenant) scope override for this request

hydradb_list

Parameter	Type	Required	Description
`kind`	string	Yes	Which family to list: `memory` or `knowledge`
`ids`	array	No	Specific IDs to filter by
`page`	number	No	Page number, 1-indexed (default: `1`)
`page_size`	number	No	Items per page, 1-100
`database`	string	No	Database (tenant) scope override for this request
`collection`	string	No	Collection (sub-tenant) scope override for this request

hydradb_inspect

Parameter	Type	Required	Description
`id`	string	Yes	The source ID to fetch content for
`mode`	string	No	`content` for text, `url` for a presigned URL, `both` for both (default: `content`)
`offset`	number	No	Character offset to start reading from
`limit`	number	No	Maximum characters to return (max `20000`)
`database`	string	No	Database (tenant) scope override for this request
`collection`	string	No	Collection (sub-tenant) scope override for this request

hydradb_delete

Parameter	Type	Required	Description
`ids`	array	No*	IDs to delete
`id`	string	No*	Single ID to delete (prefer `ids` when deleting multiple)
`kind`	string	No	Which family the ID belongs to: `memory` or `knowledge` (default: `memory`)
`database`	string	No	Database (tenant) scope override for this request
`collection`	string	No	Collection (sub-tenant) scope override for this request

hydradb_status

Parameter	Type	Required	Description
`ids`	array	Yes	The source IDs to check indexing status for
`database`	string	No	Database (tenant) scope override for this request
`collection`	string	No	Collection (sub-tenant) scope override for this request

hydradb_databases

Available on connections made with Sign in with HydraDB. Takes no parameters. Lists the databases this connection can address and marks the one it uses by default, so an agent working across several databases can find their names without asking you. If you approved the app with other databases not allowed, the list has one entry and any other name is refused.

Graph tools (BYOG openCypher)

HydraDB MCP also exposes property graph tools for querying and writing domain graphs in openCypher:

hydradb_graph_query: Run Cypher reads and writes (CREATE, MERGE, MATCH, traversals).
- Parameters: query (string, required), params (object), database (string), collection (string), max_rows (number).
hydradb_graph_collections: List graph collections in a database.
- Parameters: database (string).
hydradb_graph_admin: Manage graph databases and collections.
- Parameters: action (create_database, drop_collection, drop_database), database (string), collection (string).

hydradb_delete is irreversible.

A knowledge source cannot be deleted while it is still being indexed - the server refuses with “Source is still processing; retry deletion after ingestion completes”, and the tool passes that back rather than reporting a deletion that did not happen. Retry once ingestion finishes. This applies to freshly ingested sources only; a source is listable and inspectable before it is deletable.

Deprecated tool names

Tool names live in your mcp.json, so none were removed. Every earlier name is still registered and still works; each is marked deprecated in its description so your agent prefers the canonical one. Use the canonical names in new integrations.

Deprecated	Canonical
`hydra_db_search`	`hydradb_query`
`hydra_db_store`	`hydradb_ingest`
`hydra_db_ingest_conversation`	`hydradb_ingest` (pass `turns`)
`hydra_db_list_memories`	`hydradb_list` (`kind: memory`)
`hydra_db_list_sources`	`hydradb_list` (`kind: knowledge`)
`hydra_db_fetch_content`	`hydradb_inspect`
`hydra_db_delete_memory`	`hydradb_delete`

How It Works

At recall time, hydradb_query queries HydraDB and returns graph-enriched context - entity paths, chunk relations, and linked extra context - injected directly into the model’s prompt. At capture time, hydradb_ingest sends content with infer: true, triggering HydraDB’s knowledge graph extraction pipeline automatically. The same tool takes a document (text) or a conversation (turns), and groups related writes under source_id.

Source & Show Support

If this HydraDB MCP server makes your agentic memory workflow faster (and smarter), please star the open-source repo that powers it.

hydradb-mcp

Star on GitHub if you found it useful.

Get Started

Usage

Concepts

Plugins

For Agents

Quick Start

Authenticating to the remote server

API key headers

Self-hosting the HTTP server

Configuration

Environment Variables

Collections

Available Tools

hydradb_query

hydradb_ingest

hydradb_list

hydradb_inspect

hydradb_delete

hydradb_status

hydradb_databases

Graph tools (BYOG openCypher)

Deprecated tool names

How It Works

Source & Show Support

hydradb-mcp

​Quick Start

​What you are approving

​Authenticating to the remote server

​Sign in with HydraDB (OAuth)

​API key headers

​Self-hosting the HTTP server

​Configuration

​Environment Variables

​Collections

​Available Tools

​hydradb_query

​hydradb_ingest

​hydradb_list

​hydradb_inspect

​hydradb_delete

​hydradb_status

​hydradb_databases

​Graph tools (BYOG openCypher)

​Deprecated tool names

​How It Works

​Source & Show Support

hydradb-mcp

Quick Start

What you are approving

Authenticating to the remote server

Sign in with HydraDB (OAuth)

API key headers

Self-hosting the HTTP server

Configuration

Environment Variables

Collections

Available Tools

hydradb_query

hydradb_ingest

hydradb_list

hydradb_inspect

hydradb_delete

hydradb_status

hydradb_databases

Graph tools (BYOG openCypher)

Deprecated tool names

How It Works

Source & Show Support