Skip to main content
Version: v0.12

Vert.x Engine Configuration

Eclipse Vert.x is a reactive server framework that serves as the GraphQL API server, routing queries to the backing database/log engines.

Configuration Options​

KeyTypeDefaultNotes
authKindarray[]List of auth methods: "JWT", "OAUTH", or both
configobjectsee belowVert.x-specific configuration including auth settings

Basic Configuration​

{
"engines": {
"vertx": {
"authKind": []
}
}
}

Server Configuration Overrides​

The compiler generates the full server configuration from a built-in template and deep-merges engines.vertx.config over it, so any server setting can be overridden, not just authentication. Nested objects are merged key by key, while arrays replace the default array. Commonly overridden settings:

KeyNotes
httpServerOptions.portHTTP port (default 8888). Keep 8888 for the test command, whose test runner connects to that port
corsHandlerOptionsCORS policy. Defaults allow all origins; restrict allowedOrigin/allowedOrigins in production
poolOptions.maxSizePostgreSQL connection pool size
servletConfigEndpoint paths (graphQLEndpoint, restEndpoint, mcpEndpoint, graphiQLEndpoint), prefixed with the API version, e.g. /v1/graphql
publicGraphQLEndpointEnabledSet to false to disable the public GraphQL endpoint; REST and MCP endpoints keep working
onlyConfiguredGraphQLOperationsSet to true to only accept the predefined API operations instead of arbitrary GraphQL queries
{
"engines": {
"vertx": {
"config": {
"corsHandlerOptions": {
"allowedOrigin": "https://app.example.com",
"allowCredentials": true
},
"poolOptions": {
"maxSize": 16
}
}
}
}
}

For all settings and their defaults, see the server configuration template or the generated vertx-config.json in your build output (build/deploy/plan), which contains the effective configuration with your overrides applied.

JWT Authentication Configuration​

For secure APIs with JWT authentication:

{
"engines": {
"vertx": {
"authKind": ["JWT"],
"config": {
"jwtAuth": {
"pubSecKeys": [
{
"algorithm": "HS256",
"buffer": "<signer-secret>" // Base64 encoded signer secret string
}
],
"jwtOptions": {
"issuer": "<jwt-issuer>",
"audience": ["<jwt-audience>"],
"expiresInSeconds": 3600,
"leeway": 30
}
}
}
}
}
}

As these config fields will be mapped to Vert.x Java POJOs, the name of the key fields are very important. For pubSecKeys, it is also possible to use different algorithms, that requires the key in a different (mostly PEM) format. For example, for ES256, this would look something like this:

{
"pubSecKeys": [
{
"algorithm": "ES256",
"buffer": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhk...restOfBase64...\n-----END PUBLIC KEY-----"
}
]
}

OAuth 2.0 Authentication Configuration​

For OAuth 2.0 authentication with providers like Auth0 or Keycloak, use the oauthConfig section. This enables MCP (Model Context Protocol) clients like Claude Code to authenticate using OAuth.

{
"engines": {
"vertx": {
"authKind": ["OAUTH"],
"config": {
"oauthConfig": {
"oauth2Options": {
"site": "https://your-tenant.auth0.com/",
"clientId": "your-client-id"
},
"authorizationServerUrl": "https://your-tenant.auth0.com/",
"scopesSupported": ["mcp:tools", "mcp:resources"]
}
}
}
}
}

Combined JWT and OAuth Authentication​

You can enable both authentication methods simultaneously:

{
"engines": {
"vertx": {
"authKind": ["JWT", "OAUTH"],
"config": {
"jwtAuth": { ... },
"oauthConfig": { ... }
}
}
}
}

OAuthConfig Structure​

The oauthConfig object combines Vert.x's OAuth2Options with discovery metadata:

KeyTypeRequiredDescription
oauth2OptionsobjectYesVert.x OAuth2Options for authentication
authorizationServerUrlstringNoExternal authorization server URL for discovery
scopesSupportedarrayNoScopes advertised (default: ["mcp:tools", "mcp:resources"])
resourcestringNoPublic URL of the MCP endpoint, e.g. https://api.example.com/v1/mcp

OAuth2Options Configuration​

The oauth2Options object uses Vert.x's OAuth2Options class:

KeyTypeRequiredDescription
sitestringYesOAuth issuer URL (e.g., https://tenant.auth0.com)
clientIdstringNoOAuth client ID (defaults to datasqrl-mcp)

OAuth Discovery Endpoint​

When OAuth is configured, the server exposes a discovery endpoint at /.well-known/oauth-protected-resource per RFC 9728. This enables MCP clients to discover the authorization server and scopes. When an MCP request has no valid token, the server responds with 401 and a WWW-Authenticate: Bearer resource_metadata="..." header that points MCP clients to this endpoint.

If resource is not set, the server derives both the resource value in the discovery metadata and the resource_metadata URL from each request: the scheme from the X-Forwarded-Proto header (or the request scheme), and the host from the Host header. If resource is set, the discovery metadata returns it unchanged, and the resource_metadata URL uses its origin. For example, "resource": "https://api.example.com/v1/mcp" makes the 401 header point to https://api.example.com/.well-known/oauth-protected-resource.

Set resource when the server runs behind a reverse proxy or load balancer that terminates TLS, so MCP clients always receive https URLs. Use the exact URL MCP clients connect to: RFC 9728 requires clients to reject discovery metadata whose resource does not match that URL. The proxy must also route /.well-known/oauth-protected-resource on the same origin to the server.

Environment Variable Support​

You can use environment variables in the OAuth configuration:

{
"oauthConfig": {
"oauth2Options": {
"site": "${AUTH0_ISSUER}"
},
"authorizationServerUrl": "${AUTH0_EXTERNAL_URL}"
}
}

OAuth 2.0 with Auth0​

Auth0 is a managed identity platform that works as a drop-in OAuth 2.0 / OIDC provider for DataSQRL. Because Auth0 is a public cloud service, the issuer URL is reachable from both inside your Docker/Kubernetes network and from MCP clientsβ€”no internal vs. external URL distinction is needed.

Auth0 Setup​

1. Create an API (Resource Server)

In the Auth0 dashboard go to Applications β†’ APIs β†’ Create API and fill in:

FieldValue
NameA descriptive name, e.g. My MCP Server
IdentifierThe audience URI, e.g. https://my-mcp-server/

Enable RBAC if you want scope-based access control, then add custom scopes such as mcp:tools and mcp:resources in the Permissions tab.

2. Create a Machine-to-Machine Application

Go to Applications β†’ Applications β†’ Create Application, choose Machine to Machine Applications, and authorize it against the API you just created. Grant the scopes that MCP clients should receive.

Copy the Client ID and Client Secret β€” you will need them to request tokens.

3. (Optional) Create a Regular Web App for user-facing auth

If MCP clients authenticate on behalf of users, create a Regular Web Application instead and register your callback URL under Allowed Callback URLs.

DataSQRL Configuration​

Set site and authorizationServerUrl to your Auth0 tenant URL.

warning

The Auth0 tenant URL ends with a trailing slash, and Auth0 uses it with the slash as the issuer identifier. Keep the slash in authorizationServerUrl so the authorization server advertised to MCP clients matches Auth0's issuer exactly. For site, the slash is optional: the server removes it before fetching the OIDC discovery document.

{
"engines": {
"vertx": {
"authKind": ["OAUTH"],
"config": {
"oauthConfig": {
"oauth2Options": {
"site": "https://<your-tenant>.auth0.com/"
},
"authorizationServerUrl": "https://<your-tenant>.auth0.com/",
"scopesSupported": ["mcp:tools", "mcp:resources"]
}
}
}
}
}

Using environment variables (recommended so credentials stay out of source control):

{
"engines": {
"vertx": {
"authKind": ["OAUTH"],
"config": {
"oauthConfig": {
"oauth2Options": {
"site": "${AUTH0_ISSUER}"
},
"authorizationServerUrl": "${AUTH0_EXTERNAL_URL}"
}
}
}
}
}

Then pass the variables at compile and server startup time:

AUTH0_ISSUER=https://<your-tenant>.auth0.com/
AUTH0_EXTERNAL_URL=https://<your-tenant>.auth0.com/

Because Auth0 is a public cloud service, both variables point to the same URL.

Obtaining a Token (Client Credentials / M2M)​

For server-to-server access use the client credentials grant:

curl -s -X POST https://<your-tenant>.auth0.com/oauth/token \
-H "Content-Type: application/json" \
-d '{
"grant_type": "client_credentials",
"client_id": "<CLIENT_ID>",
"client_secret": "<CLIENT_SECRET>",
"audience": "https://my-mcp-server/"
}'

The audience field is required for Auth0 client credentials requests. Without it, Auth0 returns an opaque token rather than a JWT, which the DataSQRL server cannot validate.

Auth0-specific Notes​

  • Trailing slash on issuer β€” Auth0's issuer is always https://<tenant>.auth0.com/ (with the slash). Use that exact value for authorizationServerUrl.
  • Issuer and audience claims β€” With oauthConfig, the server only verifies the token signature against the tenant's signing keys; it does not check the iss or aud claims. Any valid token issued by the tenant is accepted, including tokens issued for other APIs of the same tenant.
  • JWKS endpoint β€” Auth0 publishes signing keys at https://<tenant>.auth0.com/.well-known/jwks.json. The server discovers them from the OIDC discovery document (/.well-known/openid-configuration) and fetches them once at startup. Restart the server after Auth0 rotates its signing keys.
  • Custom domains β€” If your Auth0 tenant uses a custom domain (e.g. https://auth.example.com/), use that URL as both site and authorizationServerUrl.

Cloud Deployment​

For cloud deployment configuration (instance sizes, instance counts), see Cloud Deployment Configuration.