# Tray Headless for Claude Code

The tray-workflows plugin for Claude Code — plan, build, validate, run, and debug Tray workflows from natural language, without leaving your terminal.

Tray Headless for Claude Code is the `tray-workflows` plugin: a guided way to build, modify, and manage Tray workflows in natural language, right inside Claude Code. Describe an integration in plain English and the plugin plans it, researches the connectors, builds the steps, validates the result, and — with your permission — test-fires it.

> **The plugin acts in your Tray workspace as you:** Once you sign in, the plugin operates with **your Tray identity and permissions**. It can create, modify, and delete projects, workflows, and authentications, and — with your explicit go-ahead — run workflows that have real side effects. Every action is taken as you, scoped to what your account can access, and only ever against the workspace you've configured.

## What it does

* **Builds and modifies Tray workflows from natural language.** Describe what you want — *"sync new Salesforce leads to Slack"* — and get a complete, validated workflow ready to run.
* **Researches connectors on demand.** Discovers any connector's operations, authentication, required fields, and dynamic-lookup values, and returns a ready-to-use step configuration.
* **Validates as it builds.** Every change is checked against Tray's structural rules server-side, so workflows are correct before they run.
* **Runs and debugs in-session.** Fires a workflow against your workspace, inspects executions, and drills into per-step input and output — without leaving the terminal.
* **Manages projects and authentication.** Creates projects, lists and reuses existing authentications, and walks through new-auth setup.

## What's in the plugin

The plugin loads the right skill automatically based on what you ask:

| Skill                | What it's for                                                                                                                       |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `build-workflow`     | The entry point for all workflow creation and modification. Runs the full build process: plan → research → build → validate → test. |
| `research-connector` | Manual connector research (operations, authentication, fields, dynamic-lookup values) for when the subagent isn't used.             |
| `tray-connectors`    | Reference for core connector names and versions, the property type-wrapper format, trigger names, and common jsonpath shapes.       |
| `tray-patterns`      | Workflow structure patterns — branches, loops, callable workflows (sync and async), scheduled triggers, and manual error handling.  |
| `tray-gotchas`       | Debugging guide for known edge cases and tricky surfaces.                                                                           |
| `set-workspace`      | User-invoked. Sets a per-project workspace override.                                                                                |

The plugin also includes a connector-research subagent, **`tray-researcher`** — an isolated agent the build process delegates to. It absorbs a connector's verbose schemas in its own context and returns a concise, typed step configuration, keeping the main conversation lean. It runs with a restricted, read-and-auth-only tool set.

## What it can do

The plugin works through the Tray platform tools below. These are the same tools the [standalone MCP server](https://tray.ai/documentation/platform/tray-headless/tray-headless-mcp) exposes.

* **Build and edit workflows:** these create and delete real resources in your live workspace — create a workflow with its trigger, add steps, update step configuration, swap a step's operation, reorganize structure (branches, ordering), update workflow metadata, remove a step, delete a workflow, and read a workflow's structure or a specific step's detail. Mutating and destructive actions (deleting a workflow, removing a step) are surfaced for your confirmation, and every change lands directly in the workspace you've configured.
* **Projects:** create a project, read a project, list projects.
* **Connectors:** search connectors, read an operation's input and output schemas, and call a connector for dynamic field-value lookups and schema discovery.
* **Authentication:** list existing authentications, list available service environments, create a new authentication request, and check its completion.
* **Validation:** run a whole-workflow structural audit (jsonpath resolution, output-shape rules, structural conventions).
* **Run and debug:** fire a workflow against the live workspace, list its executions, read an execution, and drill into a step's input and output.

## How it works

The plugin is a thin, guided client over Tray's remote MCP server at `api.tray.io/mcp`, connected directly over HTTP. There's nothing to build, install, or run locally — Claude Code connects as soon as you sign in.

The source of truth is your live Tray workspace. The plugin reads and writes through the platform API, never local files. Anything it builds is immediately visible in Tray's visual builder — that's what makes the build-headless-then-open-in-the-canvas handoff seamless.

### The build process

The `build-workflow` skill runs this every time:

1. **Plan.** Understands the request, checks the workspace for related work, asks a couple of clarifying questions, and presents a structured plan (project, workflow, trigger, steps, branching, error handling, auth, dependencies). It waits for your approval before building.
2. **Research.** For each connector — including the trigger — it discovers the version, operation schema, required fields, and any dynamic lookup values, and resolves which authentication to use.
3. **Build.** Creates the project and workflow, adds the steps, and configures each one. Dependencies (such as callable workflows) are built first.
4. **Validate.** Every change is checked server-side against Tray's structural rules; issues come back with the result so they're fixed before hand-off. A whole-workflow audit can also be run on demand.
5. **Test** *(only with explicit permission)*. Fires the workflow against your live workspace and inspects the run.

### Validation model

Validation runs in two layers, both server-side: every workflow-mutating call validates the affected steps before anything is written, and a whole-workflow audit checks that jsonpath references resolve, output shapes are correct, and structural conventions hold. The model can't write a malformed workflow.

### Workspace targeting

Every workspace-scoped call uses the Workspace ID you configured, so builds and reads target that workspace by default. The default is set at install; to work in a different workspace, set a per-project override with its Workspace ID (see [Switching workspace](#switching-workspace)).

> **Test runs have real side effects:** Firing a workflow runs every step against whatever it's wired to — a Slack step posts a real message, a Salesforce step writes a real record, a webhook calls the real endpoint. It consumes API quota and writes an execution log.

## Installation

**Requirements**

* Claude Code installed.
* A Tray workspace, including its **Workspace ID** (found in your Tray workspace settings). Authentication is a one-time browser sign-in to Tray (OAuth2) — there's no API token to generate or paste.

1. **Add the marketplace**

   ```bash
   /plugin marketplace add trayio/tray-plugins
   ```

2. **Install the plugin**

   ```bash
   /plugin install tray-workflows@tray-plugins
   ```

3. **Enter your Workspace ID and sign in**

   During install you're prompted for your **Tray Workspace ID**. On first connection the plugin opens a browser to sign in to Tray with OAuth2 — authorize once, and Claude Code holds the session. There's no API token to generate, paste, or rotate. That one-time sign-in is also what grants the agent your authority: the same step that saves you pasting a token is what lets the plugin act as you in your workspace, so it can do anything your Tray account can.

That's it — the plugin connects to Tray's hosted service over HTTP automatically. There's nothing to build or run locally.

### Verifying installation

To confirm the plugin is installed and connected correctly:

1. Check the plugin is loaded:
   ```bash
   /plugin list
   ```
   Verify `tray-workflows` appears in the list.

2. Test the connection with a simple command:
   ```bash
   List my Tray projects
   ```
   If the plugin responds with your projects, the installation is successful.

If you encounter issues, try `/reload-plugins` to refresh the plugin, or check that your Workspace ID was entered correctly during installation.

### Switching workspace

The Workspace ID entered at install is your default — every build targets it. To build in a different workspace for one project:

```bash
/tray-workflows:set-workspace <your-workspace-id>
```

This writes a per-project override to that project's local Claude Code settings; your default and other projects are unchanged. Run `/reload-plugins` afterward to apply it.

### Staying current

After an update, run `/reload-plugins` to pick up changes without restarting Claude Code.

## Getting started

Once installed, describe what you want to build:

```bash
Build a workflow that syncs new Salesforce leads to Slack
```

The plugin plans the workflow, researches the connectors it needs, builds the steps, validates the result, and — with your go-ahead — test-fires it.