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.

Run it two ways, same tools either way:

• Local (stdio) — the npx @hydradb/mcp binary each client spawns. No server to operate; credentials live in the client's config. This is the default and everything below the Configuration section documents it.
• Remote (HTTP) — one hosted process behind a URL like https://mcp.hydradb.com that many clients point at, with nothing to install. See Remote / hosted server.

Available Tools

Ids flow between these: hydradb_query, hydradb_list and hydradb_subgraph emit them;
hydradb_inspect, hydradb_delete, hydradb_status and hydradb_subgraph accept them.

Graph tools (Cypher)

Hydra DB also runs property graphs you model and own end to end, queried in Cypher. This is a different product surface from the memory and knowledge above, and nothing crosses between them: hydradb_query cannot see graph data, and hydradb_graph_query cannot see memories.

hydradb_graph_query is annotated destructiveHint, because it runs arbitrary Cypher and DELETE is as reachable through it as MATCH. There is deliberately no separate read-only Cypher tool and no read-only mode: both would mean classifying Cypher text client-side to decide what to refuse, which is a heuristic — a promise the server can keep and a client cannot. This server does not inspect your query at all; it sends it and reports what HydraDB says. To lock the graph surface down, withhold the tools (below) — that is a real guarantee.

// Everyone Alice knows within four hops
{"query": "MATCH (a:Person {name:$n})-[:KNOWS*1..4]->(r) RETURN DISTINCT r.name AS name",
 "params": {"n": "Alice"}}

// Bulk load, re-runnable after a failure
{"query": "UNWIND $rows AS row MERGE (p:Person {ext_id: row.ext_id}) SET p += row",
 "params": {"rows": [{"ext_id": "a", "name": "Alice"}]}}

Differences from Neo4j worth knowing before you write Cypher. Each is rejected before execution, so a rejected query changes nothing and fails identically on retry:

• Procedure calls (CALL db.*, CALL apoc.*) are rejected by the server, before it executes anything. CALL { ... } subqueries are fine. There is no schema tool and no apoc.meta.schema(); to learn a collection's structure, query it — MATCH (n) UNWIND labels(n) AS l RETURN l, count(*) AS c ORDER BY l.
• LOAD CSV is rejected — pass data through params instead.
• Existence checks are bare pattern predicates (WHERE (p)-[:KNOWS]->()); EXISTS { ... } and exists() are not accepted.
• shortestPath belongs in RETURN/WITH, not MATCH p = ..., and must be directed.
• EXPLAIN/PROFILE execute the query rather than planning it — do not use them to preview one.

Collections auto-create on first write, so there is no create-collection call. Requests are capped at 256 KiB (enforced locally, before upload) and large result sets are truncated server-side — paginate with ORDER BY ... SKIP $offset LIMIT $limit.

To turn the graph tools off entirely:

HYDRADB_MCP_GRAPH_TOOLS=0   # withhold all three

Deprecated aliases

The previous hydra_db_* tool names are no longer registered by default as
of 1.2.0. If your mcp.json still calls them, set:

HYDRADB_MCP_LEGACY_TOOLS=1

hydradb_query

Searches both memories and ingested knowledge sources. Returns matching
chunks with their source id, a relevance score, and knowledge-graph context.

hydradb_ingest

Saves information so it outlives the session. Provide exactly one of text
or turns.

* Passing both is an error; passing neither is an error.

Ingestion is asynchronous — content is not searchable the instant it is
saved. Use hydradb_status to confirm.

hydradb_list

Enumerates one family at a time. These are separate corpora: listing memories
tells you nothing about which knowledge sources exist.

The response reports how many of the total it showed and how to reach the rest.

hydradb_inspect

Fetches one source's full content by id.

Long sources come back in slices, and binary sources are never inlined — you get
their type and size, and mode: "url" returns a download link.

hydradb_subgraph

Returns the connected subgraph of one item: every item reachable from it through
item-level links — explicit relations declared at ingest, a shared thread,
parent/child hierarchy — traversed breadth-first. Use it when one result is not
enough and you need what surrounds it: the rest of a Slack thread, the replies
under a ticket, the documents a page links to.

Each member carries its id, title, depth from the start item and how it was
reached — discovered_relation is the mechanism (same_thread, parent,
child, or a relates_to type such as reply_to) and discovered_via the id
of the member it was reached from, so the list is also a tree.
structuredContent carries those same members, in the same order, plus
relations: the edges among them as {from, to, type}, so a client can rebuild
the graph and not just the list. truncated means max_sources clipped the
traversal; structural_link_count and structural_truncated report the
structural graph (entities, comments, attachments, actors) around the members.
Chunk-level entity relations are not included; those come from hydradb_query.

hydradb_delete

Removes items by id. Irreversible.

* Provide one of them.

hydradb_status

Checks whether ingested sources have finished indexing.

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

A graph database is a different namespace from the memory database: the same
name can exist as both, and Cypher aimed at the wrong one reads an empty graph
rather than failing. Every graph tool also takes database and collection
per call, overriding these defaults.

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

Remote / hosted server

Everything above spawns the server locally over stdio. The same server also runs
as a long-lived HTTP endpoint that many clients reach at one URL — nothing to
install or update per user. This is what powers a hosted deployment like
https://mcp.hydradb.com, and what you run yourself with npm run start:http
or the Docker image.

The tool surface is identical; only how a client connects and authenticates
changes.

Point a client at a URL

MCP clients that support a remote (streamable-http) server take a URL and
headers instead of a command:

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

Every request carries its own credentials, so one hosted process serves any
number of independent users. The headers a request may send:

* Unless the server was started with HYDRADB_API_KEY / HYDRADB_DATABASE in
its environment (single-tenant self-host, below), in which case a request may
omit them and fall back to the server's own credentials. A request that supplies
neither a header nor a server-side default is refused: 401 with no key, 400
with a key but no database.

Every tool additionally accepts optional database and collection parameters
directly in its arguments (e.g. hydradb_query with {"query": "...", "database": "tenant_b"}),
allowing multi-tenant agents to switch tenant scope per tool call while falling
back to the session defaults when omitted.

Base URL, request timeout and retry count are
operator settings read from the server's environment and are never taken
from a request header.

Run the HTTP server

Node:

npm ci && npm run build
# Single-tenant: the server holds one account; clients send no credentials.
HYDRADB_API_KEY=your-key HYDRADB_DATABASE=your-database npm run start:http
# Multi-tenant: no account in the env; every client sends its own headers.
BIND_ADDRESS=0.0.0.0 ALLOWED_HOSTS=mcp.hydradb.com npm run start:http

Docker:

docker build -t hydradb-mcp .
# Single-tenant
docker run -p 8080:8080 -e HYDRADB_API_KEY=your-key -e HYDRADB_DATABASE=your-database hydradb-mcp
# Multi-tenant (clients authenticate per request)
docker run -p 8080:8080 -e ALLOWED_HOSTS=mcp.hydradb.com hydradb-mcp

The primary MCP endpoint is / (with /mcp supported as an alias); GET /health is an unauthenticated liveness probe.
The image binds 0.0.0.0 inside the container (the host controls exposure with
-p) and runs as an unprivileged user.

Sign in with HydraDB (OAuth)

With three extra variables the hosted server also speaks the MCP authorization flow: a client that arrives with no credentials gets a 401 pointing at /.well-known/oauth-protected-resource, discovers the HydraDB dashboard as its authorization server, opens the browser, and the user signs in and picks a database. No key is ever pasted into a client.

All three are required together. With any of them missing, OAuth stays off and the server behaves exactly as before: no new routes, no new headers. Token introspection answers are memoised for up to 30 seconds, so disconnecting an app from the dashboard takes effect within that window.

OAuth is purely additive. API keys in Authorization / X-HydraDB-Api-Key headers, the X-HydraDB-Database header and the single-tenant environment fallback all keep working unchanged on the same URL.

Server environment variables

These configure the HTTP process itself (the stdio server ignores them). All
the HYDRADB_* variables from Environment Variables
also apply — as the single-tenant default and as operator settings.

Security

The defaults are safe for local use and must be widened deliberately for a
public deployment — see SECURITY.md:

• Bind loopback by default. BIND_ADDRESS stays 127.0.0.1 until you set
  otherwise; 0.0.0.0 exposes the server on every interface and logs a warning.
• Host allowlist. Requests whose Host is not loopback or in ALLOWED_HOSTS
  get 421 Misdirected Request — a DNS-rebinding defence. Add your public
  hostname when binding publicly.
• CORS is closed by default. No cross-origin browser request is accepted
  until you list its origin in ALLOWED_ORIGINS. Non-browser clients (no
  Origin header) are unaffected.
• Terminate TLS in front. Run the server behind a reverse proxy / load
  balancer that handles HTTPS; do not expose plain HTTP to the internet.

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

To run the HTTP transport locally (see Remote / hosted server):

HYDRADB_API_KEY=your-key HYDRADB_DATABASE=your-database npm run dev:http
# then: curl localhost:8080/health

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.