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

```bash
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](/docs/api-references/mcp-tools.md).

## Verification

Ask the connected client:

```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/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.

**Continue in Altertable:** [Configure MCP server](/app)

## Next steps

- [Review MCP tools](/docs/api-references/mcp-tools.md) to see the exact schemas and permissions.
- [Set up an AI client](/docs/agent-setup.md) with client-specific instructions.
- [Install the Altertable CLI](/docs/developer-tooling/cli.md) for terminal automation and structured agent output.