Skip to content
DocumentationQuery data
Query data
MCP

Model Context Protocol (MCP)

Altertable's MCP server gives AI clients a governed way to interact with your lakehouse.

Goal

Connect an MCP-compatible AI client to Altertable, authorize one environment, and verify that the client can discover Altertable tools and catalogs.

Prerequisites

  • An Altertable account with access to the organization and environment you want to query.
  • An AI client that supports hosted MCP servers over streamable HTTP and OAuth 2.0.

Clients that only support local stdio servers cannot connect to Altertable's hosted MCP server.

Steps

1. Add the server

Setting
Value
Server URL
https://mcp.altertable.ai/mcp
Transport
Streamable HTTP
Authentication
OAuth 2.0
  1. Add https://mcp.altertable.ai/mcp as an MCP server in your client.
  2. Start the connection or authorization flow.
  3. Sign in to Altertable in the browser when prompted.
  4. Choose the organization and environment the client should access.
  5. Approve the connection and return to your client.

After approval, the client uses an OAuth bearer token for MCP tool discovery and execution. Access is scoped to the environment selected during authorization.

Pin a scope

https://mcp.altertable.ai/mcp accepts either read-only or read-write access — you choose which to grant on the consent screen during authorization. To have a client request a single access level up front instead, connect it to one of the scope-pinned endpoints:

Endpoint
Access
https://mcp.altertable.ai/mcp
Read-only or read-write, chosen during authorization
https://mcp.altertable.ai/mcp/read-only
Read-only only
https://mcp.altertable.ai/mcp/read-write
Read-write only

Each pinned endpoint accepts only its own scope: a token authorized for read-only access is rejected at /mcp/read-write, and a token authorized for read-write access is rejected at /mcp/read-only. Neither endpoint silently upgrades or downgrades the other's token.

For example, to add a read-only connection in Claude Code:

claude mcp add --transport http Altertable https://mcp.altertable.ai/mcp/read-only

2. Let the client discover OAuth settings

Compatible clients should discover OAuth settings automatically. Altertable supports protected resource metadata, authorization server discovery, and dynamic client registration.

Purpose
URL
MCP server endpoint
https://mcp.altertable.ai/mcp
Protected resource metadata
https://mcp.altertable.ai/.well-known/oauth-protected-resource
Authorization server metadata
https://app.altertable.ai/.well-known/oauth-authorization-server

When a client calls an authenticated MCP method without a valid token, Altertable may return a WWW-Authenticate: Bearer ... challenge that points the client to the protected resource metadata.

3. Review tool permissions

MCP tools can list catalogs and semantic models, query the lakehouse, validate SQL, view insights and dashboards, and create outputs such as insights, memories, notifications, and scheduled tasks when write access is approved.

For the exact tool schema, see MCP tools.

Verification

Ask the connected client:

Use Altertable to list my available catalogs.

The client should discover the Altertable tools, request authorization if needed, and return catalogs from the environment selected during authorization.

Troubleshooting

  • Client cannot connect: confirm it supports hosted MCP over streamable HTTP and OAuth.
  • Discovery does not start: use exactly https://mcp.altertable.ai/mcp (or /mcp/read-only / /mcp/read-write if you pinned a scope).
  • Browser sign-in loops: finish authorization in the browser window opened by the client.
  • No tools appear: reconnect so the client reruns discovery, authorization, and tool listing.
  • Wrong environment: reconnect and choose the correct environment during authorization.
  • 403 on a pinned endpoint: the token's granted scope doesn't match the endpoint (e.g. a read-only token used against /mcp/read-write). Reauthorize with the matching scope, or connect to the bare https://mcp.altertable.ai/mcp endpoint instead.

Next steps