slab-mcp (API-key edition)

MCP server for analyzing Clay tables — schema, rows, errors, credit cost, and enrichment debugging, via Clay's public v3 API.

Connects Claude (Desktop, Code, or any MCP client) to Clay. Share any app.clay.com URL and Claude can read the schema, pull rows, trace enrichment failures end-to-end through Clay Functions (subroutines), and see exactly how many credits each cell consumed. Two installable Claude Code skills (write-clay-formula, write-claygent-prompt) cover the writing workflows.

slab authenticates with a Clay API key — cross-platform (macOS / Linux / Windows), no Chrome dependency.

What you get

• Read any Clay table or workbook — schema, formulas (full text, no truncation), run conditions, providers, dependencies, recursive function calls.

• Trace why an enrichment failed — find a row by name, get the raw provider response, follow each subroutine pointer into the child row that actually ran, recurse up to 3 levels.

• See per-row credit cost — every cell's basic credits, action-execution credits, post-2026 pricing, and underlying OpenAI/Anthropic dollar cost for AI columns. Roll-up total per row.

• Spot what's broken across a table — per-column status counts (success / error / has-not-run / queued), error message frequencies, fill rate.

• Write or fix formulas and Claygent prompts — two installable Claude Code skills (write-clay-formula, write-claygent-prompt) walk the workflow: gather inputs, pick the mode, apply the section structure and casing conventions, validate against the production-bug checklist.

Why does this exist?

Most of the interesting state in a Clay table — schema, formula text, run conditions, cell statuses, provider responses, credit cost per cell, subroutine pointers — comes back from the /v3/ API. slab wraps that API, adds session caches, and exposes the whole thing as MCP tools. This branch uses a Clay API key for auth so the server runs anywhere Node runs, with no browser or Keychain dependency.

A core design choice: slab returns structured JSON, not pre-digested prose. Earlier versions rendered markdown summaries, classified identifier values by shape, and flagged columns as "likely broken" inside the script. That's all gone. The current shape is: fetch → project to a token-cheap form → return raw JSON. Interpretation, classification, and judgment happen in the LLM. The script's job is fetching, projecting, and caching — not deciding.

Requirements

Before starting, make sure you have these installed:

1. git

Run git --version in Terminal. If you see command not found or a dialog asking to install developer tools, run:

xcode-select --install

Click Install in the dialog that appears and wait for it to finish (~5–10 min) before continuing.

2. Node.js ≥ 18

Run node -v in Terminal. If you see command not found or a version below 18:

• macOS (recommended): Download the .pkg installer from nodejs.org — click the LTS button, double-click the downloaded file, and follow the prompts. This is standalone and doesn't require Homebrew or Xcode.

• macOS with Homebrew: brew install node — only use this if Homebrew is already installed and your Xcode Command Line Tools are fully set up (i.e. step 1 above is complete).

After installing, close and reopen Terminal, then confirm with node -v.

3. A Clay API key

Go to Settings → Account → API Key in Clay and copy the key. You'll need it in Step 2 below.

Setup

Step 1 — Clone the repo and install dependencies

Run each command separately in Terminal — don't paste them all at once:

git clone https://github.com/gunnerpark-alt/slab-mcp.git

cd slab-mcp

npm install

No build step — npm install is everything. The server runs directly as node index.js. Note the directory path — you'll need it in Step 3.

Step 2 — Get your Clay API key

In Clay, go to Settings → Account → API Key and copy the key. It works across every workspace you belong to — you don't need a separate key per workspace.

Step 3 — Add slab to Claude Desktop

First, find your exact path by running this in Terminal (from inside the slab-mcp folder):

pwd

It will print something like /Users/yourname/slab-mcp. Your config path will be that output with /index.js appended.

If the config file doesn't exist yet (e.g. you just installed Claude Desktop and never opened it, or open ~/Library/Application\ Support/Claude/claude_desktop_config.json says the file doesn't exist), create it from scratch. Replace /Users/yourname/slab-mcp with your actual pwd output:

mkdir -p ~/Library/Application\ Support/Claude
cat > ~/Library/Application\ Support/Claude/claude_desktop_config.json << 'EOF'
{
  "mcpServers": {
    "slab": {
      "command": "node",
      "args": ["/Users/yourname/slab-mcp/index.js"],
      "env": {
        "CLAY_API_KEY": "paste-your-key-here"
      }
    }
  }
}
EOF

If the file already exists, open it in a text editor and add the "slab" block inside the existing "mcpServers" object — don't replace the whole file:

{
  "mcpServers": {
    "slab": {
      "command": "node",
      "args": ["/Users/yourname/slab-mcp/index.js"],
      "env": {
        "CLAY_API_KEY": "paste-your-key-here"
      }
    }
  }
}

Either way, replace paste-your-key-here with your Clay API key and /Users/yourname/slab-mcp/index.js with your actual path.

Don't put the key in args — use env so it stays out of shell history and logs.

Step 4 — Restart Claude Desktop

Fully quit the app (Cmd+Q on Mac), then reopen it. A simple window close isn't enough — the MCP server only starts on launch.

Step 5 — Verify the connection

In Claude Desktop go to Settings → Developer. You should see slab listed with a green connected indicator.

If it shows an error:

• Wrong path — run ls /path/to/slab-mcp/index.js in Terminal to confirm the file exists at the path you put in the config.

• Bad API key — make sure you copied the full key with no extra spaces.

Claude Code (alternative client)

Add to ~/.claude.json (user-level) or a project .mcp.json:

{
  "mcpServers": {
    "slab": {
      "command": "node",
      "args": ["/Users/yourname/slab-mcp/index.js"],
      "env": {
        "CLAY_API_KEY": "paste-your-key-here"
      }
    }
  }
}

Then run /mcp in Claude Code and reconnect slab.

Any other MCP client

slab is a standard stdio MCP server — anything that speaks MCP can run it:

CLAY_API_KEY=<your-key> node /Users/yourname/slab-mcp/index.js

Tools

slab exposes six data tools — what a table IS and what's IN it. Builder workflows (writing formulas, writing Claygent prompts) live in skills instead.

The MCP server's instructions field carries the full decision tree (which tool when, the cost rule of thumb between cheap surface reads and expensive nested fetches, how to follow subroutine pointers, how to interpret credit fields) — Claude sees it on every conversation that uses any slab tool.

Architecture

slab's job is to bridge Clay's internal API to an LLM. The architecture follows from one constraint and one bet:

The constraint: Clay's /v3/ API responses are huge. A single 19-column table's schema is hundreds of KB of action definitions, output schemas, and UI strings. Returning them raw would 5–10x token cost before Claude reads anything.

The bet: every other piece of judgment — what counts as "broken," whether a value is an email or a domain, how to format an explanation — is better done by the LLM than by JavaScript heuristics. Scripts are fast and deterministic but rigid; the moment Clay reworks an error string or adds a new identifier shape, a heuristic silently misclassifies. The LLM weighs context.

Together those two ideas produce slab's shape: scripts handle what the LLM can't do cheaply (auth, polling, pagination, caching, projecting away noise); the LLM handles everything else.

Layers

index.js                 MCP server, tool definitions, decision-tree instructions
src/clay-api.js          Clay v3 API client — endpoint helpers + schema projection
src/auth.js              Credential resolver (CLAY_API_KEY env → ~/.slab/config.json fallback)
src/row-utils.js         Status counting, record projection (token-cheap shape)
skills/                  Installable Claude Code skills — write-clay-formula, write-claygent-prompt

Four things are worth understanding deeper because they're what makes slab actually useful for "explain this table" / "why did X fail" questions, beyond just listing endpoints:

1. Schema sync is recursive (functions get pulled in automatically)

In Clay, a "function" is another table invoked from a parent column with actionKey: "execute-subroutine". The parent's schema tells you WHICH function runs; the function's own schema tells you HOW. Without the function's schema, any explanation of the parent is incomplete.

sync_table follows every execute-subroutine reference and syncs the target table too, recursively, up to depth 3 with a 20-table cap. sync_workbook does the same and additionally pulls in any function referenced by a workbook table that lives outside the workbook. Every fetched schema goes into the in-memory cache, so subsequent get_rows / get_record / get_errors calls on those tableIds work without a fresh sync.

The result: one call brings back the entire call graph the parent table participates in.

2. Row lookup splits by mode: server-side search for queries, paginated read for samples

get_rows has two paths, both backed by Clay's internal records API — no CSV machinery, no session caching.

With a query — server-side search. Slab posts to Clay's internal POST /tables/{tableId}/views/{viewId}/search endpoint with { searchTerm }. Clay runs the same case-insensitive substring match its own UI search box uses, returning { results: [{ fieldId, recordId }] } — one entry per matching cell, so the same record can repeat across columns. Slab dedupes by recordId, builds a matchedColumns list per match, then fetches each unique record in parallel (concurrency 5) to populate display values. One round-trip plus N record fetches, no row-count ceiling. Server caps at 1000 matching cells per response — broad substrings like "@" or a common domain may saturate it; slab surfaces a hitCapWarning when that happens.

This replaced an earlier paginate-the-whole-CSV approach that on a 100k-row table scanned forever and could fail mid-way. Server-side search returns in seconds for any table size.

Without a query — direct read. GET /records?limit=N returns the first N rows, each with its own id and cells. Slab projects cells.value to a display dict, attaches _rowId, and returns. One API call, no caching needed.

The records endpoint is also what powers get_errors and get_credits aggregate mode via listRows, which fetches up to RECORDS_API_CAP (20000) rows in one shot — the records API silently ignores every pagination param we tested (offset, cursor, after, page, ...). get_errors flags truncated in its response when the view exceeds the cap so partial counts aren't read as full coverage.

A search like "acme" will often hit multiple columns simultaneously — Name, URL, parent company. Each match's matchedColumns list is what Claude uses to pick the right hit. There's no script-side priority hierarchy.

3. Record tracing follows subroutine pointers down through execution

When a record's cell contains fullContent.origin = { tableId, recordId }, that cell is the OUTPUT of a function execution and origin is a POINTER to the row that actually ran. The parent row tells you the function "succeeded" with a display value; the child row reveals what happened inside — which provider in the waterfall ran, which inputs the parent passed in, which run conditions gated.

The MCP server's instructions require Claude to follow every origin pointer with get_record(origin.tableId, origin.recordId) before calling an execution trace complete, recursing up to 3 levels deep. Without that, "why did X fail for Y?" answers are surface-level guesses. With it, you get the full execution graph.

This is the highest-leverage thing slab does. It's also the easiest part to get wrong if you skip the follow-up calls — which is why it's spelled out in both the server instructions and the get_record tool description.

4. Credit cost rides along on every record fetch

Every action cell in a Clay record carries credit data in externalContent:

• upfrontCreditUsage.totalCost — basic credits charged for the run.

• additionalCreditUsage.totalCost — credits charged after the run completed (e.g., long-running providers).

• hiddenValue.costDetails.totalCostToAIProvider — for AI columns, the underlying OpenAI / Anthropic dollar cost.

The schema-level pricing (field.actionDefinition.pricing.credits) tells you what a column COSTS per run; the record-level usage tells you what a row ACTUALLY COST. Both are exposed:

• sync_table returns each action field's pricing (current credits + post-2026 pricing).

• get_record returns per-cell credits.{ total, upfront, additional, aiProviderCost } and a row-level _credits.{ total, billedCellCount } roll-up.

• get_credits rolls credit data up across rows in one call — pass a rowId for one row's breakdown, or omit it to sample N rows (default 50) and extrapolate a total table cost. Pass full: true to scan every row.

Subroutine cost is billed separately — and get_credits follows it. When a parent row has an execute-subroutine cell (a column that invokes another table as a function), that cell's credits is null. The actual function-call credits are billed on the function row that ran, reachable via fullContent.origin.{tableId, recordId}. get_record alone shows only the parent's direct cost, which can drastically undercount the true per-row spend on tables that use functions heavily. get_credits recursively follows the origin pointers and returns { direct, viaSubroutines, total } plus per-subroutine-column detail. Default recursion depth is 2 (parent → function → one nested level); pass subroutine_depth: 0 to disable. Aggregate mode splits the rollup into byColumn (direct cells) and bySubroutineColumn (function calls), so it's clear which Clay column triggers the most function-driven spend.

This makes "how much does this row cost" / "what's our average credit spend per row" / "which column is most expensive" / "did this AI call burn $ I didn't expect" answerable without the user opening the Clay UI.

Saved views

Clay tables expose multiple saved views — typical examples: "Default view," "All rows," "Errored rows," and any custom filtered view the table builder created. Each view returns a different row set (server-side filtered) and potentially a different ordering.

sync_table lists every available view in rootSchema.views: [{ id, name }] and picks one as the active default. The picker prefers an "All rows" view if it exists, otherwise the URL's view, otherwise the table's first view. That choice is the default for get_rows and get_errors after sync.

To query a different view without re-syncing, pass the optional view parameter to either tool. It accepts a viewId (gv_*) or a view name (case- and whitespace-tolerant — "Errored rows", "errored_rows", "ERRORED ROWS" all match the same view). The most common power move: get_errors with view="Errored rows" is much faster and more focused than scanning the whole table — it only counts statuses across already-failing rows. Same pattern works for any custom filter view ("Fully enriched rows", "Tier 1 accounts only", etc.).

Session caches

The schema cache lives in-process and vanishes when the MCP server restarts.

• schemaCache: tableId → schema. Populated by sync_table / sync_workbook, and lazily by get_rows when called with a url instead of a tableId. There is no row cache — both get_rows paths hit Clay directly each call.

Skills

slab ships two installable Claude Code skills under skills/. They're separate from the MCP server — the MCP gives Claude data tools; the skills give Claude builder workflows.

Why skills, not knowledge-base docs

Earlier versions of slab shipped a kb/ directory with reference markdown for formulas, prompts, providers, debugging, etc. — pulled in via a read_kb MCP tool. That's gone. The skills replace it.

Reference docs let Claude look things up after it's already chosen what to do. Skills shape the order of operations before any choice is made — they're a workflow with an embedded constraint set, not a cookbook. For "write a Clay formula" or "write a Claygent prompt," the workflow is the leverage. Reference material that doesn't change the order Claude does things in is mostly bulk Claude already knows from training.

Installing the skills

The skills are Claude Code-specific. Claude Desktop and direct API users don't get this scaffolding; they fall back on the MCP server's instructions field for tool selection only.

For per-user install:

mkdir -p ~/.claude/skills
cp -r skills/write-clay-formula     ~/.claude/skills/
cp -r skills/write-claygent-prompt  ~/.claude/skills/

Or symlink so updates from git pull propagate without re-copying:

ln -s "$(pwd)/skills/write-clay-formula"    ~/.claude/skills/write-clay-formula
ln -s "$(pwd)/skills/write-claygent-prompt" ~/.claude/skills/write-claygent-prompt

For project-scoped install, drop them under .claude/skills/ in the project root instead.

Verify with /skills in Claude Code.

Editing the skills

Edit the SKILL.md file directly. Skills are loaded fresh on each invocation — no build step, no MCP reconnect needed. PRs welcome.

Typical query patterns

"Sync this workbook and tell me what it does"

sync_workbook → Claude reads every table's schema + cross-table connections → explains

"Why did this enrichment fail for Acme Corp?"

get_rows(url, query="Acme Corp")
  → Claude scans matches, picks the right hit by matchedColumns
get_record(tableId, rowId)
  → record arrives with all subroutine origin pointers
get_record per origin (in parallel)
  → Claude reconstructs the full execution graph

"How much did row X cost in credits?"

get_rows(url, query="X", limit=1)
  → match comes back with _rowId
get_record(tableId, rowId)
  → record._credits.total = 10.9 across 6 billed cells
  → per-cell breakdown shows which column was most expensive
  → AI cells additionally disclose the OpenAI dollar cost

"How much does this whole table cost to run, on average per row?"

get_credits(tableId)                  # samples 50 rows, extrapolates
  → perRow.avg, perRow.min, perRow.max
  → byColumn ranked by avgCreditsPerRow (which enrichments dominate)
  → extrapolatedTotalCredits = avg × schema.rowCount

"Help me rewrite the Claygent prompt in column X"

sync_table (schema shows current prompt text in full)
  → write-claygent-prompt skill auto-triggers
  → skill picks mode (web research vs content manipulation)
  → skill walks the 12- or 10-section workflow
  → returns a rewritten prompt with proper casing, null policy, examples

"Fix this formula"

sync_table (schema shows current formula text)
  → write-clay-formula skill auto-triggers
  → skill checks sandbox traps, optional-chaining, lookup column wrapping
  → returns a corrected formula with the 10 syntax rules satisfied

"Which columns are broken across this table?"

get_errors → per-column status counts
sync_table → cross-reference with each column's run condition
  → Claude separates "broken" from "intentionally gated"

Development

npm start                # run the server directly (stdio)
node --check index.js    # syntax check

# Manual probes against a real Clay session — not real tests, just scratch scripts:
node test.js
node test-export.js
node test-workbook.js

There's no test suite yet. Contributions welcome.

Roadmap / known limitations

• Admin access required. The API key lives under your Clay account, not a workspace — it works across every workspace you're a member of, but you need admin to retrieve it.

• No persistent cache. Every server restart rehydrates from Clay. For large workbooks this is a few seconds of re-sync.

• No test suite. test*.js files are manual probes, not assertions.

License

MIT.