Setup Guide

Install the PlayKit plugin in one command to get 25 Clay MCP tools + 6 curated workflow skills — including /clay-doc, one command to document any Clay workflow.

Install the PlayKit Plugin Recommended

The fastest way to get PlayKit into your AI editor. One curl command installs the 25 Clay MCP tools plus 6 pre-curated workflow skills — including /clay-doc, one command to document any Clay workflow. Works with Claude Code, Cursor, Codex, and OpenCode. Source: github.com/orchidautomation/playkit-plugin.

Export PLAYKIT_API_KEY first. The installer reads it from your shell env and wires it into the runner — the key is never written to disk.

One-liner · Installs for every runner

export PLAYKIT_API_KEY="YOUR_API_KEY"
curl -fsSL https://github.com/orchidautomation/playkit-plugin/releases/latest/download/install-all.sh | bash

Claude Code

export PLAYKIT_API_KEY="YOUR_API_KEY"
curl -fsSL https://github.com/orchidautomation/playkit-plugin/releases/latest/download/install-claude-code.sh | bash

After install, run /reload-plugins in Claude Code to pick up the new commands.

Cursor

export PLAYKIT_API_KEY="YOUR_API_KEY"
curl -fsSL https://github.com/orchidautomation/playkit-plugin/releases/latest/download/install-cursor.sh | bash

Codex

export PLAYKIT_API_KEY="YOUR_API_KEY"
curl -fsSL https://github.com/orchidautomation/playkit-plugin/releases/latest/download/install-codex.sh | bash

Codex degrades user-defined slash commands — the 6 skills still ship fully. Invoke them by name: "use the clay-doc skill on <clay-url>".

OpenCode

export PLAYKIT_API_KEY="YOUR_API_KEY"
curl -fsSL https://github.com/orchidautomation/playkit-plugin/releases/latest/download/install-opencode.sh | bash

Source & release notes: github.com/orchidautomation/playkit-plugin

Workflow Skills New

Six pre-curated skills ship with the plugin. Each one orchestrates multiple MCP tools into a single end-to-end workflow — you invoke the skill, it picks the right tools in the right order and formats the output for you.

Skill / Command	What it does
`/clay-doc` Flagship New	One-command Clay workflow documentation. Point it at any Clay URL (table, workbook, folder, or multiple) and get a client-ready `docs/clay/…` folder with overview, build rationale, centralized AI prompts, outbound copy, sources, destinations, audit findings, and 30-day credit burn. Concern-first. Regen-safe — preserves human `<!-- WHY: -->` edits across reruns.
`/workflow-design`	Design full workflows, brainstorm GTM plays, generate ICPs, write outreach copy, craft production-ready Claygent prompts. Orchestrates `brainstorm_play`, `design_clay`, `claygent_prompts`, `generate_icp`, `write_outreach`, `get_play_catalog`.
`/table-operations`	Build, inspect, audit, run, export, and document Clay tables. Orchestrates `clay_build_table`, `clay_build_webhook_table`, `clay_get_schema`, `clay_run_enrichments`, `clay_update_column`, `clay_audit_table`, `clay_document_table`, `clay_export_data`, `clay_list_tables`, `clay_add_rows`.
`/provider-research`	Ask any Clay question, find integrations by name or capability, compare data providers side-by-side. Orchestrates `ask_clay`, `find_integrations`, `compare_providers`.
`/account-and-usage`	Check pricing tiers, current credits, per-tool costs, and upgrade options. Orchestrates `get_pricing`, `get_tool_costs`, `get_usage`, `clay_get_credits`.
`/setup-and-auth`	Connect your Clay session cookie and verify the connection before running operational workflows. Orchestrates `clay_connect`, `clay_status`.

Connect to Clay

Knowledge tools work immediately. To use Clay API tools (build tables, export data, run enrichments), connect your Clay account.

Get Your Session Cookie

Open Clay in Chrome, then grab the cookie from DevTools.

Chrome DevTools

# 1. Open app.clay.com in Chrome
# 2. Open DevTools: Cmd+Shift+I (Mac) / Ctrl+Shift+I (Win)
# 3. Go to Network tab
# 4. Click any request to api.clay.com
# 5. Copy the full Cookie header value

Connect in Claude Code

Paste it into clay_connect. This stores the cookie for your session.

Claude Code

"Connect to Clay with this cookie: <paste cookie here>"

Verify

Check the connection is active and see your workspaces.

Claude Code

"Check my Clay connection status"

You'll see your workspace name, ID, and available tables.

Clay cookies expire periodically. If API tools stop working, repeat the cookie flow above.

Raw MCP Setup

Prefer to skip the plugin and wire the PlayKit MCP server directly into your editor? This is the manual path — you get the 25 tools but none of the curated workflow skills or /clay-doc command. Most users should use the plugin install above instead.

Install PlayKit MCP

Choose your client and install method. All work on Mac and Windows.

Terminal

claude mcp add --transport http playkit \
  https://mcp.playkit.sh/mcp \
  --header "X-API-Key: YOUR_API_KEY"

~/.claude.json

{
  "mcpServers": {
    "playkit": {
      "type": "http",
      "url": "https://mcp.playkit.sh/mcp",
      "headers": {
        "X-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Codex uses TOML config and requires API keys in environment variables.

Step 1 — Set your API key

# Add to ~/.zshrc or ~/.bashrc
export PLAYKIT_API_KEY="YOUR_API_KEY"

Step 2 — Add to ~/.codex/config.toml

[mcp_servers.playkit]
url = "https://mcp.playkit.sh/mcp"

[mcp_servers.playkit.env_http_headers]
"X-API-Key" = "PLAYKIT_API_KEY"

Codex reads the PLAYKIT_API_KEY env var at runtime and sends it as the X-API-Key header. Never put the key directly in the TOML file.

Verify Connection

Check that PlayKit is connected and all tools are available.

Terminal

# Claude Code
claude mcp list

# Codex
codex mcp list

Look for playkit with a connected status and 25 tools available.

Try Your First Query

Open a Claude Code session and ask anything about Clay.

Example Prompts

# Ask anything about Clay (instant)
"What integrations find work emails without BYOA?"

# Generate production-ready Claygent prompts
"Write a Claygent prompt to find company tech stack"

# Design a full workflow
"Design an ABM workflow for fintech companies"

# Brainstorm GTM plays
"Brainstorm plays for job change signals at SaaS companies"

Knowledge Tools

Clay expertise on demand. No Clay auth required — these work immediately after install.

Tool	Description
ask_clay Popular	Ask any question about Clay. Routes to the fastest path: JSON lookup for integration facts (<10ms), graph traversal for waterfall paths, semantic search for conceptual questions.
find_integrations	Find Clay integrations by name or capability. Search 215+ providers by output type, input type, or BYOA requirement.
compare_providers	Compare data providers side-by-side — coverage, cost tier, BYOA status, best-fit scenarios, and waterfall sequence recommendations.
brainstorm_play	Brainstorm GTM plays for any use case. Returns 3-5 creative plays with integrations, Claygent prompts, and cost math using the FETC framework.
design_clay Popular	Design complete Clay workflows — from single tables to multi-table architectures. Can output a JSON build spec ready for `clay_build_table`.
claygent_prompts	Generate production-ready AI Action and Claygent prompts with step-by-step reasoning, fallback logic, edge case handling, and JSON output schemas.
write_outreach	Generate personalized cold email sequences and LinkedIn copy using Clay enrichment data and {{variables}}.
get_play_catalog	Browse the full catalog of GTM plays and patterns. Filter by category (outbound, ABM, signals, etc.) or keyword search.
generate_icp	Generate an Ideal Customer Profile from a company URL. Scrapes the site, then produces segments, personas, pain points, and signal triggers.

Clay API Tools

Build, manage, and operate Clay tables directly from Claude Code. Requires Clay auth.

Tool	Description
clay_connect	Connect your Clay session cookie. Call once per session to enable all Clay API tools.
clay_status	Check connection status, see which workspaces you have access to.
clay_list_tables	Browse tables in a workspace or workbook. Accepts any Clay URL — auto-discovers tables, schemas, and resources.
clay_get_schema	Read a table's full schema: columns, types, enrichment configs, formula definitions, and views.
clay_build_table Popular	Build a complete Clay table from a spec — workbook, table, input columns, formulas, and action columns with dependency resolution.
clay_build_webhook_table New	Create a table with a webhook source in one call. Returns the webhook URL for programmatic data ingestion. Optionally seed with initial rows.
clay_add_rows	Push data into Clay tables. Auto-detects webhook vs direct API mode.
clay_run_enrichments	Trigger enrichment columns on records in a specific view.
clay_update_column	Update an existing column's formula, prompt input bindings, or conditional run settings with resolved `{{Column Name}}` references.
clay_export_data	Export table data as JSON with human-readable column names. Filter by specific columns or row count.
clay_get_credits	Credit usage report by provider, table, and time period. Monitor spend and optimize costs.
clay_audit_table New	Deep audit of table architecture, enrichment strategy, cost efficiency, and anti-patterns. Returns scored recommendations.
clay_document_table New	Generate shareable documentation with ASCII-art data flow diagrams. Designed for git tracking and client sharing.

Account Tools

Pricing, usage, and cost estimation. No auth required.

Tool	Description
get_pricing Free	View all PlayKit pricing tiers, per-tool costs, and checkout URLs.
get_tool_costs Free	See which tools are free (JSON lookups) and which cost credits (LLM-powered). Estimate workflow costs before executing.
get_usage	Check your current tier, credits consumed, credits remaining, and upgrade options.

Troubleshooting

"Connection refused" or timeout errors

Your API key may be incorrect or the MCP wasn't installed properly.

Fix

# Remove and reinstall
claude mcp remove playkit
claude mcp add --transport http playkit \
  https://mcp.playkit.sh/mcp \
  --header "X-API-Key: YOUR_API_KEY"

"Needs authentication" in MCP list

The API key header wasn't included. Remove and re-add with the --header flag.

Tools not appearing in Claude Code

Start a fresh Claude Code session after installing the MCP. Tools load on session start, not mid-session.

Clay API tools return 401 / "not connected"

Your Clay session cookie has expired. Repeat the Connect to Clay flow to get a fresh cookie.

Update your API key

Remove the existing MCP and add it again with the new key.

Update Key

claude mcp remove playkit && \
claude mcp add --transport http playkit \
  https://mcp.playkit.sh/mcp \
  --header "X-API-Key: NEW_KEY"

500 errors or "server not responding"

The MCP server may be restarting. Wait 30 seconds and try again. If it persists, contact support.