MCP access#

Connect an MCP client to https://mcp.supernova.ai/mcp. Supernova uses OAuth 2.1 with PKCE, shows the organization attached to your active session, and lists the exact scopes before access is granted.

Scopes#

Scope	Grants
`files:read`	Lake metadata, data-repo reads, dashboard reads, and connector discovery
`files:write`	Data-repo and dashboard commits
`files:admin`	Initialize new data repos for your organization
`query:execute`	`run_query`

Access tokens last 1 hour. Refresh tokens last 30 days and can be revoked. Revocation prevents new access tokens; an already-issued access token expires at its normal boundary.

OAuth discovery#

MCP clients can discover the authorization server from either the protected-resource metadata URL for the MCP endpoint or an unauthenticated 401 response from that endpoint:

Protected-resource metadata: https://mcp.supernova.ai/.well-known/oauth-protected-resource/mcp
Authorization-server metadata: https://mcp.supernova.ai/.well-known/oauth-authorization-server

The origin-level protected-resource metadata URL is also available for clients that do not construct the path-specific URL.

Tools#

Tool	Purpose
`list_files`	Browse the virtual schema tree
`read_file`	Read a table schema and qualified SQL name
`run_query`	Run one read-only SQL statement
`list_repo_files`	List organization data-repo files at a Git ref
`read_repo_file`	Read one UTF-8 data-repo file
`write_repo_file`	Commit one UTF-8 data-repo file
`list_dashboards`	List active dashboards at a Git ref
`read_dashboard`	Read one active dashboard Markdown document
`write_dashboard`	Commit one active dashboard Markdown document
`connect_data`	Find the setup URL for an available data source or the request path for a missing connector

Data and queries#

The virtual tree organizes table metadata as <schema>/<table>.json. Each
table document identifies its qualifiedName, metadata source, and query
engine. Organizations without a legacy MCP lake, together with organizations
opted into Neutron, read metadata from Titan Catalog and run MCP queries only on
Neutron. These requests never fall back to DuckDB.

The same lake-wide metadata is queryable as
titan.information_schema.schemata, titan.information_schema.tables, and
titan.information_schema.columns. On Neutron, Supernova resolves these
relations from Titan's current lake inventory, including when the statement
does not reference any data table directly.

Connect data#

When a needed data source is not connected in Supernova, connect_data
searches the same organization-specific connector catalog shown by the app. An
exact or unique match returns the connector name and an absolute setup URL under
/apps/new. Multiple matches return their names and setup URLs so the intended
source can be clarified.

If no available connector matches, the result asks whether the connector should
be requested and returns the existing connector-request page URL. It also sets
requestSubmitted to false: opening or calling this tool does not submit a
request without that consent.

Repo and dashboards#

Repo and dashboard tools default to refs/heads/main and accept branch refs.
Every dashboard result includes url for the branch-aware live dashboard in
Supernova and previewImageUrl for a short-lived, pixel-accurate PNG capture.
The live URL opens the interactive dashboard in Supernova. The preview PNG is a
visual-verification artifact for comparing layout, styling, data presentation,
and custom-component output while a dashboard is being iterated.

The preview is the actual full dashboard, not a thumbnail. Chromium renders the
same DashboardView, theme, query results, and custom components as the app at
a fixed 1440 x 900 desktop viewport and captures the dashboard's full vertical
extent at 1x scale. Fonts, images, queries, and custom components must settle
before capture, making visual comparisons between revisions deterministic.

Each previewImageUrl contains a signed bearer token that expires after 1 hour
and is bound to the organization, user, dashboard path, and Git ref. Preview
responses are private and use no-store caching.

Query limits#

MCP queries time out after 5 minutes. Returned previews are capped at 500 rows or 100 KB. Use where, order by, and limit to make the requested result explicit.

sql

select id, amount, currency
from titan.stripe.charges
where status = 'succeeded' and not _deleted
order by created_at desc
limit 50

Lake-changing SQL is refused at statement admission. The MCP service is
organization-scoped and stateless; a token for one organization cannot name
another organization's physical lake or data repo.