# Agent setup

Connect an AI agent to Altertable with skills, hosted MCP access, and an optional CLI for terminal workflows.

## Quick setup

Paste this instruction into an AI agent with terminal and file access:

```text
Fetch https://altertable.ai/docs/agent-setup/prompt.md and follow the instructions.
```

The prompt detects the active agent, preserves existing configuration, and verifies the connection.

## Manual setup

Choose a guide for installation and troubleshooting steps:

- [Claude](/docs/agent-setup/claude.md): Install the Altertable plugin in Claude, connect the hosted MCP server, and verify access to your data catalogs.
- [ChatGPT](/docs/agent-setup/chatgpt.md): Install the Altertable plugin in ChatGPT, connect the hosted MCP server, and verify access to your data catalogs.
- [Claude Code](/docs/agent-setup/claude-code.md): Install the Altertable plugin in Claude Code, load its bundled skills and MCP configuration, and verify access to your data catalogs.
- [Codex](/docs/agent-setup/codex.md): Install the Altertable plugin from its Codex marketplace, connect the hosted MCP server, and verify access to your data catalogs.
- [Cursor](/docs/agent-setup/cursor.md): Install the Altertable Cursor plugin, connect the hosted MCP server, and verify access to your data catalogs.
- [Other agents](/docs/agent-setup/other-agents.md): Install Altertable Skills in any compatible agent without a native plugin, then add the hosted MCP server and verify catalog access.
- [Setup prompt](/docs/agent-setup/prompt.md): Copy a prompt that asks an AI agent to install the Altertable plugin, preserve existing configuration, and verify the connection.

## Tools

| Tool                  | Use when                                                                                               | Setup                                             |
| --------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------- |
| **Altertable Skills** | The agent needs Altertable-specific workflow guidance or help choosing tools                           | Installed with the plugin or Agent Skills package |
| **Altertable MCP**    | The agent can call tools interactively and needs authenticated access to Altertable data or operations | Registered by the plugin or configured manually   |
| **Altertable CLI**    | The workflow must run from a shell, CI job, or script, or needs pipeable JSON                          | Optional; install separately                      |

The [altertable-ai/skills](https://github.com/altertable-ai/skills) repository packages the skills and client plugin manifests. Compatible clients also discover the hosted MCP server:

```text
https://mcp.altertable.ai/mcp
```

For marketplace installs that ask for a qualified plugin ID, use `altertable@altertable-ai`. Clients without native plugin support should follow [Other agents](/docs/agent-setup/other-agents.md).

When the agent first uses an Altertable tool, complete authorization in your browser and choose the organization and environment it should access. See [MCP](/docs/query-data/mcp.md) for connection and permission details.

### When to add the CLI

Install the [Altertable CLI](/docs/developer-tooling/cli.md) when your agent needs to run terminal commands, automate CI, load data, or consume structured JSON. The `--agent` preset returns JSON without a pager, colors, or terminal styling:

```bash
altertable --agent query "SELECT 1"
```

The CLI is optional and installed separately. Agents can use it alongside MCP: MCP works well for interactive platform operations, while the CLI works well for shell-native workflows.

## Try Altertable

Start a new agent session after installation, then try these workflows:

1. **Explore the catalog:** “List my Altertable catalogs and explain which tables are relevant to signups.”
2. **Analyze web traffic:** “Analyze web traffic for the last 30 days and call out meaningful changes.”
3. **Analyze a funnel:** “Analyze the signup funnel from landing page to account creation.”

The agent should call `initialize` before other Altertable tools, inspect available data instead of guessing schema names, and ask before creating or changing persistent resources.

## Skills included

| Skill                          | Purpose                                                    |
| ------------------------------ | ---------------------------------------------------------- |
| `analyze-funnels`              | Analyze conversion funnels and user journeys               |
| `analyze-insights`             | Interpret chart patterns, anomalies, and trends            |
| `analyze-web-traffic`          | Analyze acquisition and web traffic patterns               |
| `ask`                          | Route a request to the best Altertable skill               |
| `build-segments`               | Build user segments and cohorts                            |
| `configure-tasks`              | Configure recurring agent tasks                            |
| `create-discoveries`           | Record meaningful findings for review                      |
| `create-insights`              | Create insights through the approval workflow              |
| `decide-actions`               | Choose the right insight or finding action                 |
| `evaluate-skills`              | Evaluate and create Agent Skills                           |
| `explore-data`                 | Explore connections, catalogs, and schemas                 |
| `forecast-timeseries`          | Analyze trends, anomalies, and forecasts                   |
| `instrument-product-analytics` | Instrument product events, identities, consent, and traits |
| `manage-discoveries`           | Manage finding review and feedback                         |
| `query-lakehouse`              | Write and run DuckDB SQL queries                           |
| `query-product-events`         | Query product events, identities, properties, and traits   |
| `query-with-chatgpt-data`      | Use Altertable as a read-only source for ChatGPT Data      |
| `understand-platform`          | Explain Altertable concepts and architecture               |
| `use-memory`                   | Store and retrieve reusable agent context                  |

Update the installed plugin or skills package when a new [Altertable Skills release](https://github.com/altertable-ai/skills/releases) is available.