---
name: pixeltable-get-started
area: Getting Started
supported_surfaces:
  - cli
  - skills
  - mcp
description: |-
  Hand your coding agent this playbook to set up Pixeltable: install
  the Python package and pxt CLI, add the Pixeltable Skill, and connect
  MCP once for use across projects.
title: 'Onboard your agent to Pixeltable'
url: https://pixeltable.com/get-started.md
runtimes:
  - Claude Code
  - Cursor
  - Codex CLI
  - VS Code with Copilot
  - Windsurf
  - Gemini CLI
  - OpenCode
---

# Set up Pixeltable for your AI coding agent

Use this playbook to prepare the current agent for Pixeltable. Install the CLI, Skill, and MCP connection once; create a Cloud database only when a hosted deploy requires it.

## How to run

Run section 1 once per machine. Run sections 2 and 3 once per coding agent.

Perform actions yourself when terminal or file access is available. Pause only for user authentication, approval, or UI actions you cannot perform. Do not merely return commands for the user to copy.

After setup, read https://pixeltable.com/llms.txt for the class-based `schema.py` Quick Start. This page is setup, not the product overview.

## 1. Install Pixeltable

Check for an existing installation:

```sh
python3 --version
pxt --version
```

Python 3.10+ is required. If `pxt` is missing, install the latest package:

```sh
pip install -U pixeltable
pxt --version
```

Serving HTTP endpoints later needs:

```sh
pip install -U 'pixeltable[serve]'
```

Do not create a Pixeltable Cloud project during global setup. Do not run `pxt schema example` yet — generate a starter schema only after the Skill is installed so the file matches current patterns.

## 2. Add Pixeltable guidance

Install the Pixeltable Skill for the current agent. This is the analog of a framework plugin: it teaches table/schema patterns, provider integrations, and anti-patterns.

```sh
npx skills add pixeltable/pixeltable-skill
npx skills list
```

Choose the current agent if prompted and confirm the installation path. Reload only if the newly installed skill is missing.

Skill source: https://github.com/pixeltable/pixeltable-skill
Skills index: https://pixeltable.com/.well-known/agent-skills/index.json

## 3. Connect MCP

Pixeltable has two MCP surfaces. Connect the one the current job needs. Do not invent a hosted authenticated control-plane MCP.

| Server | Transport | What it can do |
| --- | --- | --- |
| pixeltable-web | HTTP | Read-only docs search and integration listing. No table mutations. |
| pixeltable-developer | stdio | Inspect schemas, query tables, run a REPL against a local or Cloud catalog. |

Before changing an MCP configuration file, inspect it and merge the Pixeltable entry without replacing unrelated settings.

### Hosted WebMCP (docs, no auth)

Endpoint (exactly):

```text
https://pixeltable.com/mcp
```

Server card: https://pixeltable.com/.well-known/mcp/server-card.json

After connecting, call `search_docs` with a topic such as "embedding index" to verify.

#### Cursor

Merge this into `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "pixeltable-web": {
      "url": "https://pixeltable.com/mcp"
    }
  }
}
```

#### Claude Code

```bash
claude mcp add --transport http pixeltable-web --scope user https://pixeltable.com/mcp
```

Inspect existing MCP entries before adding.

#### Codex CLI

```bash
codex mcp list
codex mcp add pixeltable-web --url https://pixeltable.com/mcp
```

#### VS Code with GitHub Copilot

Run **MCP: Add Server**, choose **HTTP**, enter `https://pixeltable.com/mcp`, name it `pixeltable-web`, and select **Global**.

#### Windsurf

Merge this into `~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "pixeltable-web": {
      "serverUrl": "https://pixeltable.com/mcp"
    }
  }
}
```

#### Gemini CLI

Merge this into `~/.gemini/settings.json`:

```json
{
  "mcpServers": {
    "pixeltable-web": {
      "command": "npx",
      "args": ["mcp-remote", "https://pixeltable.com/mcp"]
    }
  }
}
```

### Developer MCP (stdio — tables and REPL)

Install once per machine, then add the server to the current agent:

```sh
uv tool install --from git+https://github.com/pixeltable/mcp-server-pixeltable-developer.git mcp-server-pixeltable-developer
```

If `uv` is missing:

```sh
curl -LsSf https://astral.sh/uv/install.sh | sh
```

#### Claude Code

```bash
claude mcp add pixeltable mcp-server-pixeltable-developer
```

#### Cursor

Merge this into `~/.cursor/mcp.json` (keep any existing `pixeltable-web` entry):

```json
{
  "mcpServers": {
    "pixeltable-developer": {
      "command": "mcp-server-pixeltable-developer"
    }
  }
}
```

Optional: set `PIXELTABLE_HOME` to the data directory the user wants this catalog to use.

Repository: https://github.com/pixeltable/mcp-server-pixeltable-developer

Connect the developer MCP when the user wants to inspect or query a catalog. Skip it for docs-only questions — WebMCP is enough.

Keep human confirmation enabled for every MCP mutation. The developer server can change local catalog state.

## 4. First schema (optional, after setup)

Only after sections 1–2 succeed:

```sh
pxt schema example --out schema.py
pxt schema diff schema.py my_app
```

Do not apply (`pxt schema update`) until the user confirms the plan. Cloud deploy (`pxt service create`) waits until they have an org and database.

## Completion

Report only verified state:

```text
Pixeltable agent setup is ready
CLI: <version>, pxt available
Guidance: <skill|skipped>
MCP web: <connected|skipped>, https://pixeltable.com/mcp
MCP developer: <connected|skipped>, stdio mcp-server-pixeltable-developer
MCP config: <path|not changed>
Reload: <not needed|completed>
Next: https://pixeltable.com/llms.txt
```

Sources:

- https://pixeltable.com/llms.txt
- https://pixeltable.com/developers/llms.txt
- https://docs.pixeltable.com
- https://github.com/pixeltable/pixeltable-skill
- https://github.com/pixeltable/mcp-server-pixeltable-developer
- https://pixeltable.com/.well-known/agent.json