# HelixDB Authentication for AI Agents

HelixDB uses separate credentials for database queries and the hosted HelixDB MCP server. This document describes the authentication surfaces that exist today. It does not create or advertise an autonomous agent-registration flow.

## Discover

For database queries, start with the HelixDB HTTP API documentation and OpenAPI specification:

- HelixDB HTTP API documentation: https://docs.helix-db.com/database/helix-db/query-guides/http-api
- HelixDB OpenAPI specification: https://www.helix-db.com/openapi.json
- Helix Cloud security: https://docs.helix-db.com/database/helix-cloud/operate/security

For read-only Helix Cloud insights, start with the hosted MCP server and its authoritative RFC 9728 protected-resource metadata:

- MCP server: https://mcp.helix-db.com/mcp
- Protected-resource metadata: https://mcp.helix-db.com/.well-known/oauth-protected-resource
- MCP setup guide: https://docs.helix-db.com/database/helix-cloud/connect/mcp

The MCP metadata identifies the current authorization server. Fetch it at runtime instead of hard-coding the authorization-server origin.

## Pick a method

- Local HelixDB servers do not require authentication by default.
- Helix Cloud query gateways use a cluster API key and database ID supplied through the dashboard or `helix sync`.
- The hosted HelixDB MCP server uses its existing browser OAuth flow through WorkOS.

HelixDB does not support auth.md `anonymous` registration or ID-JAG `identity_assertion` registration. An agent must use one of the existing methods above.

## Register

An authorized Helix Cloud user creates or rotates a cluster API key in the dashboard. HelixDB does not expose a `register_uri` or an `agent_auth` registration endpoint for creating one.

For MCP, use an OAuth-capable MCP client. The client connects to https://mcp.helix-db.com/mcp, follows the `WWW-Authenticate` protected-resource metadata link, and completes the existing browser authorization flow.

Do not send cluster keys to discovery endpoints or put them in source control, agent instructions, `llms.txt`, or catalog manifests.

## Claim

HelixDB does not implement an anonymous claim ceremony, email claim flow, or ID-JAG account-linking flow. There is no claim endpoint to call. Complete MCP authorization in the browser as directed by the discovered authorization server.

## Use the credential

Send a Helix Cloud cluster API key and database ID with each query request:

```http
Authorization: Bearer <cluster-api-key>
X-Helix-Database-Id: <database-id>
```

For MCP, let the client store and present the OAuth access token. Do not copy that token into prompts or agent-readable documentation.

## Errors

- A Helix Cloud query `400 Bad Request` means the authentication header is missing or malformed. A `401 Unauthorized` means the supplied cluster API key is invalid. Re-check the selected database and rotate the key if necessary.
- A Helix Cloud query `402 Payment Required` means query processing is disabled because credit is exhausted. A `403 Forbidden` means the key lacks permission for the requested operation.
- A Helix Cloud query `408 Request Timeout` means the query exceeded its wall-clock limit and can be retried according to the application's retry policy.
- An MCP `401 Unauthorized` includes `WWW-Authenticate: Bearer resource_metadata="https://mcp.helix-db.com/.well-known/oauth-protected-resource/mcp"`. Follow that metadata link and restart OAuth.
- Do not probe a `register_uri`, claim URI, or identity-assertion endpoint: HelixDB does not advertise or operate those endpoints.

## Revocation

- Revoke or rotate a cluster API key in the Helix Cloud dashboard, then update every authorized client that used it.
- For MCP, disconnect HelixDB in the client and remove the stored connection credential. The current authorization server does not advertise a token revocation endpoint.

## Support

- Developer resources: https://www.helix-db.com/developers
- Terms: https://www.helix-db.com/terms
- Privacy: https://www.helix-db.com/privacy
- Support: https://discord.gg/2stgMPr5BD