Starburst MCP server#

Starburst Enterprise includes an integrated Model Context Protocol (MCP) server that lets AI agents and large language model (LLM) applications securely query your Starburst cluster. MCP server on Starburst Enterprise exposes a stateless, authenticated HTTP endpoint for programmatic data access.

Note

This feature is available as a public preview. Contact your Starburst account team for more information.

Requirements#

  • A valid AI_WORKFLOWS license.

Configuration#

Add the following property to your coordinator configuration file to enable the Starburst MCP server:

starburst.mcp.enabled=true

The MCP server is then available at the https://<coordinator-host>:<port>/mcp endpoint URL.

General configuration properties#

The following general configuration properties must be added to the coordinator configuration file.

Property name

Description

Default

starburst.mcp.enabled

Enable the MCP server on the coordinator.

false

mcp.query.max-result-size

Specifies the maximum size of result data returned to clients. You can set this value between 64kB and 8GB. Queries that return results larger than the configured limit fail. It is recommended to keep this value low for agent use cases.

1MB

Fault-tolerant execution support#

The MCP server does not support custom retry-policy configurations for clusters using fault-tolerant execution. Any existing retry policy configurations are overridden. Policy overrides only affect queries that are run using the MCP server.

Querying data#

The server provides a query tool that lets AI agents and LLM applications run read-only queries against your cluster and receive structured results in JSON format. Queries run synchronously. The agent waits for the query to finish before returning a response. Response times may be longer for large or complex queries.

Note

The result set size must be smaller than the value of mcp.query.max-result-size. If the result exceeds this limit, the query fails with an error.

Input format#

The following example shows a request used by an agent that retrieves five rows from the tpch.tiny.nation table:

{
  "query": "SELECT name, regionkey FROM tpch.tiny.nation ORDER BY name LIMIT 5"
}

The tool accepts the following input parameter:

Input parameter#

Parameter

Type

Description

query

string

The SQL query to execute. This is a required property.

Response format#

The MCP server returns structured JSON similar to the following example, continuing the query of the tpch.tiny.nation table.

{
  "queryId": "1234abcdefg",
  "columns": [
    {"columnName": "name", "columnType": "varchar"}
    {"columnName": "regionkey", "columnType": "bigint"}
  ],
  "rows": [
    ["ALGERIA", "0"]
    ["ARGENTINA", "1"]
    ["BRAZIL", "1"]
  ]
}
Query returned attributes#

Attribute

Type

Description

queryId

string

Unique identifier for the executed query.

columns

array

List of column metadata objects.

columnName

string

Name of column.

columnType

string

Data type of the column. For example, "VARCHAR" or "BIGINT"

rows

array

Array of result rows. Each row is an array of stringified values. Null values are represented as "null".

Unsupported SQL operations#

The query tool supports only read-only SQL queries. It rejects any query that contains the following operations:

  • INSERT

  • UPDATE

  • DELETE

  • MERGE

  • TRUNCATE

  • GRANT

  • REVOKE

  • CREATE, ALTER, or DROP statements for tables, schemas, or catalogs.

Limitations#

  1. Result Size Limit: Query results are capped by the mcp.query.max-result-size configuration property.

    • queries returning results larger than this limit fail.

    • instruct agents to LIMIT clauses or filters to reduce result sizes for large datasets.

  2. Queries follow standard Starburst query timeout configurations.

  3. Queries are subject to resource management rules and terminate if they exceed configured limits.

Authentication and authorization types#

The MCP server requires authentication for all requests and supports the same authentication methods as running queries. Authentication uses your existing SEP configuration. For more information about authentication types, see authentication types.

Clients must provide authentication credentials in standard HTTP headers when making requests to the MCP server. The MCP server supports all headers defined in the Starburst Client Protocol specification.

General configuration properties#

The following authentication and authorization configuration properties should be added to the coordinator configuration file.

Property name

Description

Default

mcp.auth.scopes-supported

Comma-separated list of OAuth scopes to advertise MCP clients. For example: mcp.auth.scopes-supported=openid,email,profile This property is optional.

Defaults to the scopes in http-server.authentication.oauth2.scopes.

mcp.auth.servers.override

Override the authorization server URLs advertised in the OAuth metadata resource endpoint. This property is optional.

mcp.auth.custom.metadata

Add additional custom metadata entries to the OAuth Protected Resource Metadata response. For example: mcp.auth.custom.metadata=custom_property:value1,another_claim:value2.

mcp.cors.allowed-origins

Configures Cross-Origin Resource Sharing (CORS) for the OAuth metadata endpoint. For example: mcp.cors.allowed-origins=https://app.example.com,https://dashboard.example.com.

OAuth scopes#

Specify the OAuth and OpenID Connect scopes supported by the MCP server. This must be a subset of the supported scopes defined in the http-server.authentication.oauth2.scopes parameter.

mcp.auth.scopes-supported=openid,email,profile

This configuration appears in the OAuth Protected Resource Metadata endpoint, https://<coordinator-host>:<port>/.well-known/oauth-protected-resource, and informs MCP clients which scopes to request when obtaining access tokens.

OAuth metadata endpoint#

When OAuth 2.0 http-server.authentication.type=oauth2 or delegated OAuth http-server.authentication.type=delegated-oauth2 is enabled, the coordinator exposes an RFC 8414-compliant OAuth Protected Resource Metadata endpoint:

GET https://<coordinator-host>:<port>/.well-known/oauth-protected-resource

This endpoint provides the following metadata required by OAuth clients for automatic configuration with the MCP server:

  • resource: The base URL of the Starburst MCP Server

  • resource_name: “Starburst MCP”

  • authorization_servers: List of authorization server URLs from either OAuth configuration or override.

  • jwks_uri: JSON Web Key Set endpoint for token verification

  • scopes_supported: List of supported OAuth scopes

Custom OAuth metadata#

You can add custom metadata entries to the OAuth Protected Resource Metadata response.

The following example defines two additional metadata fields registration_endpoint and okta_api:

mcp.auth.custom.metadata=registration_endpoint:https://<auth_server>/register,okta_api_key=<api_key>

Two more metadata fields are included in the protected resources response. The protected resource metadata endpoint is publicly available. Users who have read access to your SEP cluster can view this metadata.

Authorization servers override#

Override the list of authorization servers advertised in the OAuth metadata resource endpoint.

mcp.auth.servers.override=https://auth.example.com,https://backup-auth.example.com

If unset, the authorization server displayed in the protected resource metadata endpoint defaults to the issuer URL from http-server.authentication.oauth2.issuer.

Dynamic client registration#

MCP can interoperate with authorization servers that support OAuth 2.1 Dynamic Client Registration protocol (DCR), allowing MCP clients to register automatically.

The MCP spec on authorization recommends supporting the OAuth DCR to dynamically generate client IDs and secrets for MCP sessions. DCR allows MCP clients to register automatically with your OAuth authorization server without manual configuration. DCR support depends on your authorization server, not on Starburst Enterprise. Starburst does not support management of dynamic clients with any authorization servers.

Configuration#

If your authorization server supports DCR, follow these steps to enable it:

  1. Enable DCR on your authorization server, if not enabled by default.

  2. Configure registration endpoint: Ensure your OAuth metadata includes the registration_endpoint field.

  3. Set appropriate scopes: Configure which scopes are available for dynamically registered clients.

  4. MCP Client Configuration: MCP clients can discover the registration endpoint from the authorization server metadata and automatically register.