Pixeltable Developer MCP Server

A local Model Context Protocol server for building, inspecting, and operating
Pixeltable applications. Version 0.2 follows the
application-first workflow in pixeltable-skill 2.8.3: generate one app.py, apply its schema, and serve its routes with the pxt CLI.

Compatibility

The server is a beta developer tool. It runs with the permissions of the
process that launched it and can mutate the selected Pixeltable catalog. Point
PIXELTABLE_MCP_PROJECT_ROOT at the application directory and PIXELTABLE_HOME
at the intended catalog before startup. Both locations are fixed for the life of
the process. Use a separate catalog for evaluation and automated tests.

Install and connect

Install uv, then install the server:

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

For reproducible development from a clone:

git clone https://github.com/pixeltable/mcp-server-pixeltable-developer.git
cd mcp-server-pixeltable-developer
uv sync --frozen --extra test

Configure a client to launch the server over stdio. Replace the repository,
application project, and catalog paths with absolute paths:

{
  "mcpServers": {
    "pixeltable": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/mcp-server-pixeltable-developer",
        "mcp-server-pixeltable-developer"
      ],
      "env": {
        "PIXELTABLE_MCP_PROJECT_ROOT": "/absolute/path/to/pixeltable-app",
        "PIXELTABLE_HOME": "/absolute/path/to/.pixeltable"
      }
    }
  }
}

Restart the client after changing its MCP configuration. Keep one server
process per catalog when performing schema or service mutations.

Default interface

Version 0.2 exposes a focused interface instead of mirroring the whole
Pixeltable Python API.

Tools

Read tools declare read-only MCP annotations. Mutation tools declare their
write and destructive behavior. Arguments and results use typed schemas, and
recoverable failures are returned as MCP tool errors so clients can retry with
corrected input.

Resources

Prompts

• pixeltable_build_app
• pixeltable_build_rag
• pixeltable_build_agent
• pixeltable_debug_computation

The prompts are short task guides aligned with pixeltable-skill 2.8.3. The
skill remains the detailed source for provider output shapes, multimodal views,
indexes, tool calling, serving, debugging, and Cloud workflows.

Unsafe mode

Host-code execution, package installation, and browser display are disabled by
default. A trusted local user can opt in before starting the server:

export PIXELTABLE_MCP_ENABLE_UNSAFE=1

This adds:

• pixeltable_unsafe_execute_python
• pixeltable_unsafe_install_package
• pixeltable_unsafe_display

These tools are available only on stdio. They can execute arbitrary Python,
change the server environment, read files available to the server process, and
render untrusted content. Enable them only for a trusted, local MCP client and
a disposable development environment. Do not expose unsafe mode through an
HTTP transport.

The repository may use an in-process or HTTP harness in tests. HTTP is not a
supported production transport for version 0.2. A future HTTP release must add
authorization, concurrency and request limits, origin and host validation,
per-principal isolation, and an explicit threat model before it is supported.

Recommended Pixeltable workflow

Start an application with the current Pixeltable CLI:

pip install 'pixeltable[serve]>=0.7.6,<0.8'
pxt init
pxt service example --out app.py
pxt schema check app.py
pxt schema diff app.py my_app
pxt schema update app.py my_app
pxt service check app.py
pxt service update app.py my_app
pxt service list

my_app is a catalog directory. It is not a filesystem directory. Edit
app.py and apply the schema again when the model changes. Apply the service
again after route changes. Use pxt service list to discover the assigned URL.

The application file should declare TableModel classes and, when HTTP routes
are needed, a FastAPIRouter. Stored columns use annotations. Computed columns
use assignments. Types are non-nullable by default; write T | None for an
optional column. Do not use pxt.Required.

Schema updates intentionally require a review step. schema_check validates
the file, schema_diff previews catalog changes, and schema_update applies
them. Prune operations are separate because they can remove catalog objects.
Changing an existing computed-column expression in place is unsupported by
Pixeltable; rename the column, or drop and re-add it in separate updates.

For Cloud, prepare the same app.py, set PIXELTABLE_API_KEY, configure the
target pxt://org:db, and review pixeltable://guidance/cloud. The MCP server
does not create paid resources or deploy to Cloud automatically.

Develop and verify

Use a disposable catalog:

export PIXELTABLE_MCP_PROJECT_ROOT="$PWD"
export PIXELTABLE_HOME="$(mktemp -d)/catalog"
uv sync --frozen --extra test
uv run pytest -q
PIXELTABLE_DISABLE_STDOUT=1 uv run pytest --run-slow -q
uv run python list_tools.py
./scripts/run-conformance.sh

Run the MCP Inspector only as a local test harness:

uv run mcp dev src/mcp_server_pixeltable_developer/server.py:mcp

Before release, also run the latest-dependency compatibility job, the MCP
in-memory contract tests, the subprocess stdio smoke test, lint, type checks,
and package build verification described in the review report.

Privacy Policy

The server runs entirely on the machine that starts it. It collects no telemetry
and no analytics, and it sends nothing to Pixeltable or to any third party.

What it handles. The Pixeltable catalog at PIXELTABLE_HOME and the
application files under PIXELTABLE_MCP_PROJECT_ROOT, both chosen by you. Tool
results are returned to the MCP client that launched the server, which is how
your assistant reads them. Nothing else receives them.

Storage and retention. The server stores nothing of its own. Catalog data
stays in PIXELTABLE_HOME on your disk, under your control, and is removed when
you remove it.

Secrets. Command output is passed through a redactor that masks common
credential forms, including URL passwords and API tokens, before it reaches the
client.

Third parties. If your application declares computed columns that call model
providers, Pixeltable makes those calls with the credentials you configured. That
traffic is your application's, not this server's.

Unsafe mode. With PIXELTABLE_MCP_ENABLE_UNSAFE=1, the added tools execute
arbitrary Python, install packages, and read files available to the server
process. Enable it only on a trusted local machine.

Contact. Report privacy questions through
GitHub issues.

Documentation

• 0.1.0 evidence review
• 0.2.0 implementation review
• Migration from 0.1 to 0.2
• Agent evaluation protocol
• Pixeltable documentation
• Pixeltable get started
• Pixeltable LLM reference
• MCP Python SDK 2 documentation

License

Apache-2.0. See LICENSE.