# Tray Headless MCP

Connect any MCP-compatible client — Cursor, Codex, Windsurf, or your own agent — to the hosted Tray MCP server at api.tray.io/mcp.

Tray Headless MCP is a hosted MCP server at **`api.tray.io/mcp`** that exposes the Tray platform as MCP tools over HTTP. There's nothing to install or run — it's a remote endpoint your MCP client connects to.

It exposes the same capability surface as the [Claude Code plugin](https://tray.ai/documentation/platform/tray-headless/headless-for-claude-code): build and edit workflows, projects, connectors, authentication, validation, and run and debug. The plugin is one client of this server, with a guided build process, skills, research subagent, and workspace pinning layered on top. The raw server gives you the tools, and you (or your agent) drive them.

> **These tools act in your Tray workspace as you:** Once you complete the OAuth2 sign-in, the server's tools operate with your Tray identity and permissions. They can create, modify, and delete projects, workflows, and authentications, and run workflows that have real side effects — every call is made as you, scoped to what your account can access, against the workspace you pass. The packaged plugin surfaces destructive actions for confirmation; a raw client applies only the guardrails you give it, so review what your agent is allowed to do.

## Who it's for

Anyone working in an MCP-compatible client other than the packaged Claude Code plugin — for example **Cursor, Codex, Windsurf**, Claude Code configured by hand, or a custom agent you're building. Use it when you want Tray's platform tools available to your own AI workflow.

## How to connect

`api.tray.io/mcp` is a **Streamable HTTP** MCP server that uses interactive **OAuth2**. Add it to your client's MCP configuration, then complete a one-time browser sign-in to Tray — there's no token to generate or carry.

Two things to keep in mind:

* **Don't add an `Authorization` header.** Supplying a static token switches the client into token-based auth and prevents the interactive OAuth2 sign-in.
* **Supply your Workspace ID.** Most Tray platform calls are workspace-scoped and take a Workspace ID per call, so pass it to your client or agent. (The packaged plugin pins this for you; raw clients pass it explicitly.)

### Cursor

Add Tray to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project):

```json
{
  "mcpServers": {
    "tray": {
      "url": "https://api.tray.io/mcp"
    }
  }
}
```

Then open Cursor's settings, find the `tray` server under Tools and MCP, and click **Needs login** to complete the browser sign-in.

### Windsurf

Add Tray to `~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "tray": {
      "serverUrl": "https://api.tray.io/mcp"
    }
  }
}
```

Windsurf uses `serverUrl` (not `url`) for remote servers. After adding it, complete the authorize prompt that appears in the MCP panel to sign in. Use a recent Windsurf build for the smoothest OAuth experience.

### Codex

Add Tray to `~/.codex/config.toml`:

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

Then authenticate from the CLI:

```bash
codex mcp login tray
```

This opens the browser sign-in. Remote MCP servers with OAuth require a recent version of the Codex CLI.

### Claude Code

> **Note:** For Claude Code, the [Tray Headless for Claude Code plugin](https://tray.ai/documentation/platform/tray-headless/headless-for-claude-code) is the recommended path — it adds the guided build process, skills, research subagent, and workspace pinning. Configure the raw server by hand only if you specifically want the tools without the plugin layer.

Add the server with the CLI:

```bash
claude mcp add --transport http tray https://api.tray.io/mcp
```

Then run `/mcp` inside a session and follow the browser sign-in to authorize.

The exact configuration keys vary slightly by client; the snippets above are the verified shape for each. For a side-by-side comparison of the plugin and the standalone server, see the [Tray Headless overview](https://tray.ai/documentation/platform/tray-headless/overview#which-should-i-use).