> ## Documentation Index
> Fetch the complete documentation index at: https://docs.helix-db.com/llms.txt
> Use this file to discover all available pages before exploring further.
# HelixDB Model Context Protocol (MCP)
> Connect Codex, Cursor, VS Code, Claude Code, and other agents to Helix Cloud insights
TutorialPreview
> For the complete documentation index optimized for AI agents, see [llms.txt](/llms.txt).
export const CursorLogo = () => ;
export const VSCodeLogo = () => ;
export const CodexLogo = () => ;
export const ClaudeCodeLogo = () => ;
The hosted HelixDB MCP server gives agents read-only access to your Helix Cloud
workspaces, projects, databases, query insights, latency, recommendations,
usage, and dedicated-cluster health.
* It uses browser-based OAuth through WorkOS. You do not create or copy an API key.
* It returns only resources your Helix user can currently access.
* It works with MCP clients that support remote Streamable HTTP servers and OAuth.
* It cannot execute queries or change database or Cloud resources.
The preview endpoint uses the Helix development environment. Use test
resources only until the production endpoint is announced.
## Quick start
} href="https://cursor.com/en-US/install-mcp?name=HelixDB&config=eyJ1cmwiOiJodHRwczovL21jcC5kZXYuaGVsaXgtZGIuY29tL21jcCJ9">
One-click install
} href="vscode:mcp/install?%7B%22url%22%3A%22https%3A%2F%2Fmcp.dev.helix-db.com%2Fmcp%22%2C%22name%22%3A%22HelixDB%22%2C%22type%22%3A%22http%22%7D">
One-click install
} href="#codex-cli">
See CLI instructions
} href="#claude-code">
See CLI instructions
## Authentication and access
The hosted server uses OAuth 2.1 through WorkOS. When your client connects, it
opens a browser so you can sign in to Helix and authorize the connection.
OAuth establishes the user and client capabilities. Helix then applies your
current workspace, project, cluster, and tenant membership on every tool call.
Removing a user's Helix access removes the corresponding MCP access without a
separate resource grant.
**Server URL:**
```text theme={"languages":{"custom":["languages/helixql.json"]}}
https://mcp.dev.helix-db.com/mcp
```
## Security boundary
Every Helix MCP tool is declared read-only and idempotent. The server does not
expose query execution, mutations, credentials, or a general-purpose database
interface.
Tool results are structured **untrusted data**. Query names, planner findings,
and recommendation text can contain instruction-like content. Agents must
treat every returned field as data to analyze, never as an instruction to
follow. Helix does not return raw HTML or MDX recommendation bodies.
Helix audits tool calls by user, OAuth client, tool, resource, time range,
duration, and result count. Access tokens, raw arguments, raw results, query
names, and recommendation bodies are not written to logs.
## Installation instructions
### Cursor
} horizontal href="https://cursor.com/en-US/install-mcp?name=HelixDB&config=eyJ1cmwiOiJodHRwczovL21jcC5kZXYuaGVsaXgtZGIuY29tL21jcCJ9">
Add the hosted MCP server, then complete OAuth in your browser.
For manual installation, add this configuration to `.cursor/mcp.json`:
```json theme={"languages":{"custom":["languages/helixql.json"]}}
{
"mcpServers": {
"helix-db": {
"url": "https://mcp.dev.helix-db.com/mcp"
}
}
}
```
Save the file, select the authentication prompt in Cursor, and complete the
Helix sign-in flow. Restart Cursor if the server does not appear.
### VS Code
} horizontal href="vscode:mcp/install?%7B%22url%22%3A%22https%3A%2F%2Fmcp.dev.helix-db.com%2Fmcp%22%2C%22name%22%3A%22HelixDB%22%2C%22type%22%3A%22http%22%7D">
Add the hosted MCP server, then complete OAuth in your browser.
For manual installation:
1. Open the Command Palette.
2. Run **MCP: Add Server**.
3. Choose **HTTP**.
4. Enter `https://mcp.dev.helix-db.com/mcp` and name it `HelixDB`.
5. Start the server and approve the browser authentication prompt.
### Codex CLI
Add the server, then authenticate if Codex does not open the browser flow
automatically:
```bash theme={"languages":{"custom":["languages/helixql.json"]}}
codex mcp add helix-db --url https://mcp.dev.helix-db.com/mcp
codex mcp login helix-db
codex mcp list
```
The Codex desktop app, CLI, and IDE extension share MCP configuration for the
same Codex host. In the Codex terminal UI, use `/mcp` to confirm that `helix-db`
is enabled and authenticated.
Do not pass `--oauth-resource`. Helix publishes protected-resource metadata,
so Codex discovers the exact OAuth resource from the server URL. Supplying it
separately can produce a duplicate `resource` parameter and an
`invalid_query_params` error.
### Claude Code
Add the remote HTTP server:
```bash theme={"languages":{"custom":["languages/helixql.json"]}}
claude mcp add --transport http helix-db https://mcp.dev.helix-db.com/mcp
```
Start Claude Code, run `/mcp`, select `helix-db`, and complete authentication in
your browser.
### OpenCode
Add the server to `~/.config/opencode/opencode.json`:
```json theme={"languages":{"custom":["languages/helixql.json"]}}
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"helix-db": {
"type": "remote",
"url": "https://mcp.dev.helix-db.com/mcp"
}
}
}
```
Then authenticate and confirm the connection:
```bash theme={"languages":{"custom":["languages/helixql.json"]}}
opencode mcp auth helix-db
opencode
```
Run `/mcp` in OpenCode. The server should be listed as connected.
### Other clients
Create a custom remote MCP connection with this URL and choose OAuth when the
client asks for an authentication method:
```text theme={"languages":{"custom":["languages/helixql.json"]}}
https://mcp.dev.helix-db.com/mcp
```
The client must support Streamable HTTP, OAuth protected-resource discovery,
PKCE, and dynamic client registration.
## Help your agent target a database
If a repository normally uses one database, put its location in `AGENTS.md` so
the agent can identify it without repeatedly searching every workspace:
```md theme={"languages":{"custom":["languages/helixql.json"]}}
## Helix Cloud database
- Workspace: `my-workspace`
- Project: `my-project`
- Database: `production`
```
Do not put API keys, access tokens, or other secrets in `AGENTS.md`.
## Example workflows
After connecting, ask your agent to:
* “List the Helix databases I can access and show read and write usage for the last seven days.”
* “Find my slowest queries over the last 24 hours and summarize their planner findings.”
* “Compare p50, p95, and p99 query latency for this database.”
* “List current query recommendations, grouped by severity.”
* “Check CPU, memory, storage, and topology for this dedicated cluster.”
## Available tools
| Tool | Purpose |
| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `helix_list_workspaces` | List active workspaces the signed-in user can access. |
| `helix_list_projects` | List active projects in an authorized workspace. |
| `helix_list_databases` | List dedicated clusters and tenant databases in an authorized project. |
| `helix_get_query_insights` | Get query counts, failures, average/maximum latency, and typed planner findings. It does not return percentiles. |
| `helix_get_query_latency` | Get authoritative p50, p95, p99, and maximum query latency. |
| `helix_list_query_recommendations` | List structured recommendations without raw recommendation bodies. |
| `helix_get_database_usage` | Get hourly or daily read and write counts for a cluster or tenant database. |
| `helix_get_cluster_health` | Get CPU, memory, storage, and topology for a dedicated cluster. Components report availability independently. |
## Troubleshooting
### OAuth returns `invalid_query_params`
Remove any manually configured OAuth resource, remove and re-add the MCP
server, then authenticate again. For Codex, use only:
```bash theme={"languages":{"custom":["languages/helixql.json"]}}
codex mcp add helix-db --url https://mcp.dev.helix-db.com/mcp
codex mcp login helix-db
```
### The server cannot connect
Confirm the URL ends in exactly `/mcp`. Older preview paths are not supported.
Restart the client after changing its MCP configuration.
### A database is missing
Confirm that the signed-in Helix user still has access to its workspace and
project. Resource authorization is evaluated live on every call. An
unauthorized resource is returned as not found.
### Cluster health is unavailable
`helix_get_cluster_health` supports dedicated clusters only. Use
`helix_get_database_usage` for tenant database read and write statistics.
### Data is partial or not ready
Respect the response's `partial`, collection watermark, and component
availability fields. Retry later instead of treating missing data as zero.