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 organization as you

Once you sign in, the plugin operates with your Tray identity and permissions in the workspace you select during sign-in. It can create, modify, and delete projects, workflows, and authentications, and run workflows that have real side effects. What it's allowed to do is governed by the permissions you grant it in Claude Code.

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.

The plugin also includes a connector-research subagent, tray-researcher, that researches available connectors and their operations on demand.

What it can do

The plugin works through the Tray platform tools below. These are the same tools 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 your live workspace.
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 plugin connects to the US endpoint (api.tray.io/mcp) only — it does not support regional endpoints. If your workspace is in the EU or APAC region, use the Tray Headless MCP server with your region's endpoint instead.

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:

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.
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.
Build. Creates the project and workflow, adds the steps, and configures each one. Dependencies (such as callable workflows) are built first.
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.
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.

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. Authentication is a one-time browser sign-in to Tray (OAuth2), during which you select the workspace to work in — there's no API token to generate or paste, and no Workspace ID to look up.

The tray-workflows plugin is available at github.com/trayio/tray-plugins.

Add the marketplace

/plugin marketplace add trayio/tray-plugins

Install the plugin

/plugin install tray-workflows@tray-plugins

Sign in and select your workspace

On first connection the plugin opens a browser to sign in to Tray with OAuth2. Select the workspace you want to work in when prompted — that choice binds your session to that workspace, and every build lands there. Authorize once and Claude Code holds the session; there's no API token to generate, paste, or rotate, and no Workspace ID to enter. 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.

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:

Check the plugin is loaded:
/plugin list
Verify tray-workflows appears in the list.
Test the connection with a simple command:
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 sign in again and confirm you selected the right workspace.

Switching workspace

Your session targets the workspace you chose when you signed in. To work in a different workspace, sign in again and select the other workspace during the OAuth2 flow — the new selection rebinds your session.

After switching, start a new Claude Code session so the plugin picks up the newly selected workspace.

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:

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.