---
title: MCP access
description: Connect an MCP client to Supernova, grant scoped access, inspect lake schemas, and run bounded read-only queries.
species: guide
---
# MCP access

Connect an MCP client to `https://mcp.supernova.ai/mcp`. Supernova uses OAuth 2.1 with PKCE, asks you to choose an organization, and shows the exact scopes before access is granted.

## Scopes

| Scope | Grants |
|---|---|
| `files:read` | `list_files` and `read_file` |
| `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.

## 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 |

The virtual tree organizes table metadata as `tables/<schema>/<table>.json`. Start by listing files, read the relevant table, then use its `qualifiedName` in SQL.

## 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.