Connecting Clients

Altertable's MCP server is designed for MCP-compatible clients that support streamable HTTP plus OAuth. In most clients, setup is simple: enter the MCP server URL, start the connection, then complete authorization in the browser.

Before You Connect

Your MCP client should support:

• hosted MCP servers over HTTP
• OAuth-based authorization
• bearer-token MCP sessions after approval

If your client only supports local stdio servers or does not support MCP OAuth flows yet, it won't work with Altertable's hosted MCP server.

Connection Settings

Use the following values when your client asks for MCP server details:

For most users, the server URL is the only value they need to enter manually.

Authorization Flow

The usual connection flow looks like this:

1. Add Altertable as an MCP server in your client.
2. Start the connection or authorization flow from the client.
3. Let the client discover Altertable's OAuth metadata automatically. Depending on the client, this may happen from the first bearer auth challenge or directly from the well-known metadata endpoints.
4. Sign in to Altertable in the browser if prompted.
5. Choose the organization and environment you want the client to access.
6. Approve the connection and return to the client.

After approval, the client can call Altertable MCP tools inside the selected environment.

That environment contains the same core objects you use elsewhere in Altertable, including Connections, Insights, Dashboards, Discoveries, and Memories.

What the User Chooses

When Altertable asks for authorization, the important choice is the environment.

That selection determines which data the MCP session can access:

• connections
• semantic models
• product analytics events and traits
• saved insights and dashboards
• discoveries, and memories

If you need the agent to work in a different environment later, reconnect and authorize the client against that environment instead.

What to Do After Connection

Once connected, help the agent build context before asking it to create anything:

1. Confirm which organization and environment the session is using
2. List the available data connections
3. Inspect the semantic models, events, or traits that look relevant
4. Query or preview before creating new assets

If you want a broader picture of how data access works outside MCP too, see Client Interfaces.

What to Ask First

Once connected, start with small orientation prompts before jumping into analysis:

• "What organization and environment is this session connected to?"
• "List the available data connections."
• "Show me the semantic models for this environment."
• "List the latest saved insights and dashboards."
• "Search the Altertable docs for guidance on semantic insights."

This helps the agent build context before it starts querying or creating assets.

Typical Usage Pattern

Most MCP sessions follow the same path:

1. Orient: identify the organization and environment
2. Explore: inspect connections, schemas, semantic models, events, and traits
3. Analyze: run SQL, preview insights, inspect dashboards and discoveries
4. Act: create insights, memories, or discoveries if needed

Troubleshooting

If the connection doesn't behave as expected:

• Client cannot connect at all: verify that the client supports hosted MCP servers over streamable HTTP and supports OAuth
• Discovery does not start: check that the MCP server URL is exactly https://mcp.altertable.ai/v1
• Browser sign-in loop: make sure you are signed in to Altertable and complete the authorization flow in the browser window the client opens
• No tools appear after approval: reconnect so the client re-runs discovery, authorization, and tool listing
• Wrong environment: reconnect and choose the correct environment during OAuth approval
• Permission confusion: remember that the MCP session is scoped to the environment selected during authorization

Next Steps

• Authentication: Learn how Altertable's MCP OAuth flow works
• Concepts: Agents: Understand how agents fit into the broader Altertable platform
• Insights: Learn the analysis types agents can inspect and create
• Dashboards: Understand the collections of insights agents can review and monitor