---
name: hypertab
description: Operate Hypertab through MCP to create Project-owned programmable Tables, manage records and columns, run API workflows, configure views and sources, and inspect activity. Use whenever a user wants an MCP client to organize or execute durable structured work in Hypertab.
metadata:
  version: 4.2.0
---

# Hypertab

Hypertab is a project-first workspace. Every Table belongs to a Project; executable columns, sources, views, and record state do the work.

Do not create or recommend standalone Pages, blocks, Notion-like documents, Workbooks, dashboard builders, hosted UI surfaces, user-deployed Functions, or intake-table objects. Those paths are retired.

## Session Start

1. Read `hypertab://skill`; it is the current server-provided guidance.
2. Read `hypertab://tables` to inspect Tables, columns, and record counts.
3. Trust live `tools/list` schemas over examples in this file.
4. Use `hypertab_list_projects` before creating a Table when its target Project is unclear.

## Product Model

```text
Workspace
  Home
  Projects
    Project
      Table
        Records
        Columns
        Views
        Sources
        Runs
```

- Create structure with `hypertab_create_project`, `hypertab_list_projects`, and `hypertab_create_table` with `project_id`.
- Use `hypertab_add_table_to_project` only to move or repair ownership of an existing Table.
- Store durable structured data in Tables, not local-only files.
- Use Table descriptions, long-text fields, record detail, views, and activity for supporting context.

## Connection And Links

- MCP: `https://api.hypertab.ai/mcp`
- Auth: `Authorization: Bearer ht_sk_...`
- App: `https://app.hypertab.ai`

Use workspace-scoped links:

```text
https://app.hypertab.ai/workspaces/{workspace}/projects/{project_id}
https://app.hypertab.ai/workspaces/{workspace}/tables/{table_id}
```

Get `{workspace}` from `hypertab_list_workspaces`. Avoid historical `/pages/...` links.

## Plan Calls By Intent

### Observe

Inspect without mutation:

- `hypertab_list_tables`
- `hypertab_get_table_schema`
- `hypertab_query_rows`
- `hypertab_get_row`
- `hypertab_count_rows`
- `hypertab_describe_column`
- `hypertab_list_views`
- `hypertab_get_dag`
- `hypertab_get_stats`
- `hypertab_get_usage_summary`
- `hypertab_get_errors`
- `hypertab_export_csv`

Read-only access can still expose full Table data through queries and export. Treat it accordingly.

### Operate

Change Table structure or records:

- Table lifecycle: `hypertab_create_table`, `hypertab_update_table`, `hypertab_delete_table`, `hypertab_restore_table`.
- Columns: `hypertab_add_column`, `hypertab_update_column`, `hypertab_delete_column`.
- Smart columns: `hypertab_add_smart_column`, `hypertab_add_extract_column`.
- Records: `hypertab_insert_rows`, `hypertab_update_rows`, `hypertab_upsert_rows`, `hypertab_delete_rows`, `hypertab_restore_rows`.
- Data quality: `hypertab_import_csv`, `hypertab_dedupe_column`.
- Views: `hypertab_create_view`, `hypertab_update_view`, `hypertab_delete_view`.

Inserting or editing records can trigger `auto_run` smart columns and spend external API credits.

### Execute

Run existing work with `hypertab_run_column`, `hypertab_run_dag`, `hypertab_retry_failed_cells`, `hypertab_sync_tab`, `hypertab_http_request`, and the relevant approval or connected-agent execution tools.

### Sources And Webhooks

- Receive data with `hypertab_create_source` using `type: webhook`.
- Update sources in place with `hypertab_update_source`.
- Use endpoint tools only for advanced route auth, transforms, logs, and replay.
- Treat replay as execution because it can insert records and trigger work.

## Reliable Write Rules

- Read the Table schema before writing records or configuring templates.
- Use stable `idempotency_key` values on write tools that expose one.
- Reuse the same key only when retrying the same logical operation.
- Preview destructive bulk changes with `hypertab_count_rows`.
- Restate ambiguous destructive intent before the first mutation.
- Batch inserts instead of calling tools in a loop.
- Follow response `hints` for the logical next action.
- On `SCOPE_DENIED`, do not retry. Use `details.current_scopes` and request the required scope.

Suggested key: `agent:{tool}:{target}:{batch-or-hash}`.

## Smart Columns

Use smart columns for repeatable per-record work:

- `http`: call user-chosen external APIs.
- `formula`: deterministic calculations.
- `lookup`: retrieve values from another Table.
- `waterfall`: try sources in order until one succeeds.
- `integration`: push downstream.
- `extract`: parse structured values from existing content.

Workflow:

1. Read the Table schema.
2. Save external credentials with `hypertab_save_api_account` when needed.
3. Add the smart column.
4. Run it on a bounded record set.
5. Inspect run status and failed cells.
6. Report the external service, target count, successes, failures, and usage when available.

Use `{{column_name}}` templates in HTTP URLs and bodies. Formula expressions use bare column names. Never call an API once per record from the agent; let smart-column execution handle batching, retries, rate limits, and circuit breakers.

## Views

Views present one existing Table as Grid, Board, Calendar, Form, Gallery, or Timeline. They do not create a Page, dashboard, or new backend data object.

For chart or summary requests, derive the result from Table data and use the closest existing Table view or return the analysis directly. Do not invent Page/block tools.

## Common Workflows

### Create A Project-owned Table

1. `hypertab_list_projects`.
2. Reuse the appropriate Project or call `hypertab_create_project`.
3. `hypertab_create_table` with that Project's `project_id`.
4. Add columns, records, sources, and views as requested.
5. Return the direct Table link.

### Import And Enrich Data

1. Resolve or create the Project-owned Table.
2. Import CSV or batch-insert records.
3. Inspect schema and sample records.
4. Add the smallest useful smart-column DAG.
5. Run a small sample before a full batch.
6. Inspect errors and usage.

### Receive Webhook Records

1. Resolve or create the Project-owned Table.
2. Create a webhook Source.
3. Configure advanced route auth/transforms only if needed.
4. Return the public webhook URL and direct Table link.
5. Verify with a bounded test payload when authorized.

### Monitor Work

Use run status, cell states, errors, usage, source logs, webhook logs, and activity tools. Report concrete state rather than assuming success.

## Scopes

- `observe`: read, query, and export.
- `operate`: mutate Tables, columns, records, and views.
- `execute`: run work and approvals.
- `page:build`: legacy scope name used only for Project/Table ownership.
- `endpoint:manage`: configure webhook routes.
- `bridge` or `bridge:client`: report connected-agent work.
- `artifact:write`: attach outputs.
- `admin`: manage credentials and mint keys through REST.

API key creation is not an MCP tool. Direct users to workspace MCP/API-key settings or the authenticated REST key route.

## Connection Lifecycle

- Create, rename, regenerate, or revoke individual MCP/API keys from the app's MCP settings page.
- Diagnose local wrapper setup with `bridge wrapper doctor`.
- Regenerating one key revokes only that key, preserves its name/scopes/workspace, and shows the replacement once.
- Remove Hypertab MCP plus its installed skills from every supported client on a Mac with:

```bash
npx @hypertabai/mcp uninstall --all
```

- Remove only Hypertab skill files while keeping MCP connections configured with:

```bash
npx @hypertabai/mcp uninstall --all --skills-only
```

Uninstall is idempotent and preserves unrelated MCP servers and skills.

## Safety And Trust

- Never expose private Hypertab API keys to public webhook senders.
- Never reveal stored API-account or environment secrets.
- Do not claim security, isolation, retention, compliance, or billing behavior beyond what live docs/tools confirm.
- Do not retry usage-limit errors blindly; reduce scope, wait, or ask the user to adjust limits.
- Preserve existing Projects and Tables unless deletion is explicit.

## Retired Tool Guard

Ignore old instructions for Page or block creation, Workbooks, dashboards, user-deployed Functions, runtime surfaces, publishing, or chart-to-surface flows. If a live server unexpectedly exposes a compatibility tool for one of those paths, do not use it for new product work.