# Set up Codex

The Altertable Codex plugin packages Altertable Skills and the hosted MCP configuration.

## Quick start

1. Open Codex from the root of the project where you want to use Altertable. If **Altertable** is available in your Plugins directory, install it there and skip steps 2 and 3.

2. Add the Altertable marketplace:

   ```bash
   codex plugin marketplace add altertable-ai/skills
   ```

3. Install the plugin:

   ```bash
   codex plugin add altertable@altertable-ai
   ```

4. Start a new Codex session so it loads the plugin.

5. Ask Codex to analyze a real workflow:

   ```text
   Analyze web traffic for the last 30 days and call out meaningful changes.
   ```

The first Altertable tool call opens OAuth authorization in your browser. Choose the organization and environment Codex should access, then return to Codex.

## Verify

List installed plugins and MCP servers:

```bash
codex plugin list
codex mcp list
```

Then ask:

```text
Use Altertable to list my available catalogs.
```

Codex should call `initialize` first and then inspect the catalogs.

## Tools

- [Altertable Skills](/docs/agent-setup.md#skills-included) provide workflows for exploration, SQL, funnels, web traffic, insights, and platform operations.
- [Altertable MCP](/docs/query-data/mcp.md) provides governed access to catalogs, queries, insights, findings, and tasks.
- The optional [Altertable CLI](/docs/developer-tooling/cli.md) supports shell automation, CI, ingestion, SQL, and structured agent output.

If you only need the MCP server, add it without installing the plugin:

```bash
codex mcp add altertable --url https://mcp.altertable.ai/mcp
```

Do not add a duplicate when `codex mcp list` already shows the server.

### Choose between Skills, MCP, and the CLI

Use Skills for workflow guidance, MCP for interactive Altertable operations, and the CLI for terminal automation, CI, ingestion, or structured JSON. The CLI is optional and installed separately; Codex can use it alongside MCP.

## Update

Refresh released skills from the configured marketplace:

```bash
codex plugin marketplace upgrade altertable-ai
```

Then open `/plugins` to install the available Altertable update.

## Troubleshooting

- **Plugin is missing:** run `codex plugin marketplace list`, refresh the Altertable marketplace, and install the plugin again.
- **Skills do not appear:** start a new Codex session after installation or update.
- **MCP server is missing:** install the plugin again or add the hosted server directly.
- **Authorization does not finish:** complete the browser flow opened by Codex and choose an organization and environment.
- **Wrong environment is connected:** remove the Altertable MCP connection and authorize it again with the correct environment.