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.
Requirements#
To use MCP server, you need:
A valid MCP server 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 |
|---|---|---|
|
Enable the MCP server on the coordinator. |
|
|
Sets the maximum duration that a query can run when
executed through the MCP |
|
|
Specifies the maximum size of result data returned to clients. You can set
this value between |
|
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:
Parameter |
Type |
Description |
|---|---|---|
|
|
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"]
]
}
Attribute |
Type |
Description |
|---|---|---|
|
|
Unique identifier for the executed query. |
|
|
List of column metadata objects. |
|
|
Name of column. |
|
|
Data type of the column. For example, |
|
|
Array of result rows. Each row is an array of stringified values. Null
values are represented as |
Unsupported SQL operations#
The query tool supports only read-only SQL queries. It rejects any query that contains the following operations:
INSERTUPDATEDELETEMERGETRUNCATEGRANTREVOKECREATE,ALTER, orDROPstatements for tables, schemas, or catalogs.
Limitations#
Result Size Limit: Query results are capped by the
mcp.query.max-result-sizeconfiguration property.queries returning results larger than this limit fail.
instruct agents to
LIMITclauses or filters to reduce result sizes for large datasets.
Queries follow standard Starburst query timeout configurations.
Queries are subject to resource management rules and terminate if they exceed configured limits.
Starburst AI Agent via MCP#
This tool exposes the Starburst AI Agent through MCP. It lets an authenticated MCP client open a stateful conversational AI agent session within a specific data product and interact with that agent using a configured model alias.
To use the AI Agent over MCP, you need:
Data products enabled.
Access to at least one configured language AI model. The agent uses the model alias when invoked through MCP.
Configuration#
Add the following properties to your coordinator configuration file.
Property name |
Description |
Default |
|---|---|---|
|
Sets the maximum duration a request waits to start if another request from the same client session is already running for the same data product. If the request does not start within this time, it fails. |
|
|
Specifies the AI model alias used when invoking
the data product AI agent through MCP. For example, |
The agent runs with the identity configured in the MCP connection. All actions the agent performs are subject to the privileges and access controls of that identity.
Session history#
A data product agent session through MCP is created the first time a client sends a request during an MCP session for a specific data product. The session remains associated with that MCP session and data product for the lifetime of the MCP connection. To start a new session for the same client and data product, the MCP client must reconnect and establish a new MCP session.
Agent sessions initiated through MCP appear in the data product agent session history. However, MCP sessions are read-only in the UI.
Concurrent requests that target the same agent session are serialized so that
only one request runs at a time. Additional requests are queued and wait up to
the duration configured by
mcp.tool.data-product-agent.concurrent-request-timeout. If a request does not
start within this time, it fails.
