# 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](https://developers.openai.com/codex): 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](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 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.

> **Note:** 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](https://tray.ai/documentation/platform/tray-headless/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:

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.

> **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](https://developers.openai.com/codex) 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](#manual-setup-older-codex-builds) 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.

> **Note:** The `tray-workflows` plugin is available at [github.com/trayio/tray-plugins](https://github.com/trayio/tray-plugins).

1. **Add the marketplace and install the plugin**

   ```bash
   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.

2. **Authorize**

   The Tray MCP server uses OAuth2 (PKCE). Sign in once:

   ```bash
   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.

3. **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.

### Manual setup (older Codex builds)

If your Codex build doesn't have the plugin marketplace, wire up the MCP server by hand.

1. **Add the MCP server.** Merge this block into `~/.codex/config.toml` (or a project-level `.codex/config.toml`):

   ```toml
   [mcp_servers.tray]
   url = "https://api.tray.io/mcp"
   ```

   Some Codex releases gate remote/HTTP MCP transport behind an experimental flag. If `codex mcp list` doesn't show `tray`, add the following near the top of `config.toml` and restart Codex (try without it first):

   ```toml
   [features]
   experimental_use_rmcp_client = true
   ```

2. **Sign in** with `codex mcp login tray`, then record your workspace as described in step 3 above.

To also get the guided skills and the `tray-researcher` subagent on a manual setup, copy the plugin's `skills/` into `~/.agents/skills/` (or `.agents/skills/` in your project) and its `agents/tray-researcher.toml` into `~/.codex/agents/`.

### Verifying installation

To confirm the plugin is installed and connected correctly:

1. Check the `tray` MCP server is registered:

   ```bash
   codex mcp list
   ```

   Verify `tray` appears in the list.

2. 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.