Skip to content
DocumentationAgents
Agents
Model Context Protocol (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. Log 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. You must belong to its organization and have permission to use that environment. Tools are filtered by the granted tier, resource permissions, enabled product features, and connected integrations. Reconnect and authorize again to change the environment or scope.

Start with https://mcp.altertable.ai/mcp and grant Read-only access for exploration. Choose Analyst when you need to create analyses or data apps. Choose Full access only when you need lakehouse writes or schema changes.

Pin a scope

https://mcp.altertable.ai/mcp supports Read-only, Analyst, and Full access. Choose the least access your workflow needs on the consent screen. Read-only lets an agent explore and query data. Analyst also allows it to create, edit, and delete analyses such as insights, dashboards, and data apps. Full access adds lakehouse data writes and schema changes. 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, Analyst, or Full access, chosen during authorization
https://mcp.altertable.ai/mcp/read-only
Read-only only
https://mcp.altertable.ai/mcp/analyst
Analyst only (mcp:analyst)
https://mcp.altertable.ai/mcp/read-write
Full access only (mcp:rw)

Each pinned endpoint requires its exact tier. A token granted another tier, including a broader one, receives 403 insufficient_scope. The bare /mcp endpoint accepts all three tiers and gates each tool by its minimum scope.

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

Terminal
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 and follow the metadata URL in the server’s WWW-Authenticate challenge. Pinned endpoints provide path-specific metadata. 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 the granted tier and resource permissions allow it.

For the exact tool schema, see MCP tools.

Verification

Ask the connected client:

Plain text
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/analyst, or /mcp/read-write if you pinned a scope).
  • Browser login 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