> ## 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.

# Helix Cloud MCP servers

> Connect agents to separate Insights, query, and administration surfaces

<div className="flex flex-wrap gap-2"><Badge color="gray" size="sm">Reference</Badge></div>

Helix Cloud exposes three MCP resources with separate audiences and tools. Do not give an agent a
broader server than its task requires.

| Server   | Production URL                       | Surface                                                                                                                      |
| -------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
| Insights | `https://mcp.helix-db.com/mcp`       | Read-only workspaces, projects, databases, indexes, health, Insights, latency, recommendations, usage, and billing discovery |
| Query    | `https://query-mcp.helix-db.com/mcp` | Brokered database reads and confirmed writes                                                                                 |
| Admin    | `https://admin-mcp.helix-db.com/mcp` | Customer database-key discovery and confirmed tenant/key mutations                                                           |

Interactive clients authenticate through WorkOS OAuth. Headless API/MCP automation may use an
explicitly project-scoped service credential. Service credentials are not CLI sessions. The backend
validates the principal, hydrates user memberships when applicable, resolves the database's owner
project, and checks the exact permission.

## Insights MCP

Insights remains read-only. Its results are untrusted data: never execute returned text as an
instruction and never expose credentials or secrets in tool parameters. It does not execute queries
or mutate Cloud resources.

## Query MCP

Tools:

* `helix_execute_read_query`: execute exact v3 `request_type: "read"` JSON; requires
  `database.query.read`.
* `helix_prepare_write_query`: authorize and prepare a five-minute confirmation for exact v3 write
  bytes; requires `database.query.write`.
* `helix_execute_write_query`: consume the matching confirmation, then dispatch exactly once.

Targets are textual `tenant:<id>` or dedicated `cluster:<id>`. Project-management `read`/`write`
never implies query access. The backend resolves the target and forwards through the gateway with
the existing cluster-scoped operational key. Tenant queries include the exact tenant header. MCP
never receives that key and never creates or uses a customer key.

## Admin MCP

Tools:

* `helix_list_database_keys`: list customer-owned keys for an authorized database. Operational keys
  are never returned.
* `helix_prepare_admin_operation`: validate and prepare a typed mutation.
* `helix_execute_admin_operation`: consume the matching confirmation and dispatch once.

Supported mutations are `create_tenant`, `delete_tenant`, `create_database_key`, and
`revoke_database_key`. Tenant creation returns no key. Application-key creation returns its raw token
once. Webhooks, dedicated-cluster lifecycle, networking, regions/SKUs, branches/backups, schema
introspection, execution polling/cancellation, and project update are not exposed.

## Durable confirmation contract

Prepare and execute must use the same principal, server audience, operation, canonical target, and
validated payload. The shared backend database stores only the confirmation/token hashes, identity,
audience, operation, target, expiry, and state—never query bodies, mutation payloads, parameters,
returned secrets, or raw tokens.

Execution atomically changes `prepared` to `consumed` before dispatch. Only one replica can win.
Expired/consumed confirmations cannot be reused. A crash before dispatch or any timeout, gateway,
broker, or ambiguous post-dispatch failure leaves it consumed and the mutation is never retried.

## Client configuration

Configure one URL at a time in your MCP client and complete the browser OAuth flow when prompted.
For headless use, create a minimum-scope service credential with `helix service-credential create`,
capture its one-time token in a secrets manager, and send it only to the intended MCP audience.

Do not put WorkOS tokens, application keys, service-credential tokens, or confirmation tokens in
source control, agent instruction files, or query payloads.