Tray Headless for Codex

The tray-workflows plugin for the OpenAI Codex CLI — plan, build, validate, run, and debug Tray workflows from natural language, without leaving your terminal.

Tray Headless for Codex is the tray-workflows plugin packaged for the OpenAI Codex CLI: a guided way to build, modify, and manage Tray workflows in natural language, right inside Codex. 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 — the same access your Tray account has across your whole organization, not just the workspace you configured. 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 Codex.

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`	Records the active workspace in `AGENTS.md` (per-project, overriding the global setting).

The plugin also includes a connector-research subagent, tray-researcher, that researches available connectors and their operations on demand. If subagents aren't available in your Codex build, the plugin follows the research-connector skill inline instead.

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 or run locally — Codex connects as soon as you authorize.

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

The Codex CLI installed and on your PATH, on a build that includes the plugin marketplace. To check, run codex plugin --help — it should list a marketplace command. On older builds, use the manual setup below.
A Tray workspace, including its Workspace ID (found in the Tray app URL — see step 3). Authentication is a one-time browser sign-in to Tray (OAuth2) — there's no API token to generate or paste.

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

Add the marketplace and install the plugin
codex plugin marketplace add trayio/tray-plugins codex plugin add tray-workflows@tray-plugins
This registers the skills, the tray-researcher subagent, and the remote tray MCP server. Alternatively, run codex and use /plugins to install tray-workflows interactively.
Authorize

The Tray MCP server uses OAuth2 (PKCE). Sign in once:
codex mcp login tray
Your browser opens to authorize. After that, Codex manages tokens automatically — there's no API token to generate, paste, or rotate.
Set your workspace

Codex has no per-plugin config prompt, so the active workspace is recorded as a line in AGENTS.md:
Active Tray Workspace: <your-workspace-id>
Add it to your project's AGENTS.md, or to ~/.codex/AGENTS.md to set it globally; a project AGENTS.md overrides the global one. Find the UUID in the Tray app URL: https://app.tray.io/workspaces/<ID>/.... You can edit the line by hand, or ask Codex to run the set-workspace skill. The Workspace ID you set is the default target for new builds — it doesn't limit access; because the plugin operates as you, it has the same access your Tray account does, including other workspaces in your organization.

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 tray MCP server is registered:
codex mcp list
Verify tray appears in the list.
Test the connection from a Codex session:
List my Tray projects
If it responds with your projects, the installation is successful.

If you encounter issues, confirm you've run codex mcp login tray and that your Active Tray Workspace: line in AGENTS.md holds a valid Workspace ID.

Switching workspace

The Active Tray Workspace: line in AGENTS.md is the default for builds. To build in a different workspace for one project, set a project-level AGENTS.md line — it overrides the global ~/.codex/AGENTS.md:

Active Tray Workspace: <your-workspace-id>

Edit it by hand, or ask Codex to run the set-workspace skill.

Staying current

After updating the plugin or its marketplace, restart Codex to load the changes.

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.